@vitrindigital/node 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +10 -0
  2. package/dist/index.d.cts +51 -2
  3. package/dist/index.d.ts +51 -2
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -24,6 +24,16 @@ const vitrin = new Vitrin({
24
24
 
25
25
  Use a chave `vd_test_*` em desenvolvimento e `vd_live_*` em produção.
26
26
 
27
+ ## Organizações LLC (US)
28
+
29
+ Se a org é uma **US LLC** (`entity_type: "llc"`), os valores são em **USD**
30
+ (campo `currency` nas transações); os métodos default são **cartão** e **Pix
31
+ cross-border** (o cliente paga em BRL, a LLC recebe em USD). A liquidação é
32
+ **automática**: os endpoints de saldo/recebíveis/transferências retornam
33
+ `{ auto_payout: true }` em vez de saldo retido (não há saque/antecipação
34
+ manual). O onboarding inclui verificação de identidade (KYC), hospedada ou
35
+ embedded. Veja `docs/api/onboarding-llc.md` e `docs/api/differences-cnpj-llc.md`.
36
+
27
37
  ## Recursos
28
38
 
29
39
  ### Clientes
package/dist/index.d.cts CHANGED
@@ -43,8 +43,42 @@ declare class VitrinClient {
43
43
  * Mantidos como interfaces genéricas (em vez de unions super-precisas) pra
44
44
  * que mudanças não-quebra-API no backend não exijam major bump no SDK.
45
45
  */
46
- type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD';
46
+ /** ISO 4217. BRL é o default histórico; USD/EUR/GBP habilitados com orgs LLC. */
47
+ type Currency = 'BRL' | 'USD' | 'EUR' | 'GBP';
48
+ /** Tipo jurídico da organização. CNPJ = subconta Safe2Pay (Brasil),
49
+ * LLC = Stripe Connect (US/internacional). */
50
+ type EntityType = 'cnpj' | 'llc';
51
+ /**
52
+ * Métodos de pagamento suportados pela plataforma.
53
+ *
54
+ * A disponibilidade por org é dinâmica — sempre cheque
55
+ * `Organization.enabled_payment_methods`. Por tipo de entidade:
56
+ *
57
+ * - CNPJ (BR): PIX, PIX_AUTOMATIC, BOLETO, CREDIT_CARD (default).
58
+ * - LLC (US): CREDIT_CARD por default. PIX está disponível cross-border
59
+ * (o cliente paga em BRL, a liquidação é em USD) como opt-in habilitado
60
+ * pela Vitrin. BOLETO NÃO se aplica a LLC (é Brasil-only). Os demais
61
+ * métodos abaixo (cartão internacional / ACH / wallets / Klarna /
62
+ * Afterpay) são reservados para evolução e podem não estar habilitados.
63
+ */
64
+ type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD' | 'CARD_INTERNATIONAL' | 'ACH_DEBIT' | 'SEPA_DEBIT' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'KLARNA' | 'AFTERPAY';
47
65
  type TransactionStatus = 'pending' | 'confirmed' | 'received' | 'overdue' | 'refunded' | 'chargeback' | 'failed' | 'canceled';
66
+ /**
67
+ * Representa a organização (subconta) dona da API key em uso.
68
+ *
69
+ * Nota: `default_currency` é derivado de `entity_type` no backend e pode
70
+ * ainda não estar exposto pelo serializer — a declaração aqui é
71
+ * forward-compatible para quando o backend passar a emiti-lo.
72
+ */
73
+ interface Organization {
74
+ id: string;
75
+ name: string;
76
+ entity_type: EntityType;
77
+ default_currency: Currency;
78
+ enabled_payment_methods?: PaymentMethod[];
79
+ created_at: string;
80
+ updated_at: string;
81
+ }
48
82
  interface Customer {
49
83
  id: string;
50
84
  name: string;
@@ -94,6 +128,11 @@ interface Subscription {
94
128
  canceled_at: string | null;
95
129
  created_at: string;
96
130
  updated_at: string;
131
+ /** LLC: moeda da assinatura (USD). Ausente/BRL para CNPJ. */
132
+ currency?: Currency;
133
+ /** LLC: secret de confirmação da 1ª cobrança — quando presente, confirme
134
+ * com Stripe.js (cartão/SCA) antes da assinatura ficar ativa. */
135
+ client_secret?: string | null;
97
136
  }
98
137
  interface Transaction {
99
138
  id: string;
@@ -106,6 +145,16 @@ interface Transaction {
106
145
  platform_fee: string;
107
146
  provider_fee: string;
108
147
  billing_type: PaymentMethod;
148
+ /** ISO 4217. Default herdado de `Organization.default_currency` na criação. */
149
+ currency: Currency;
150
+ /** LLC: secret de confirmação — cartão (SCA/3DS) ou PIX (QR); confirme com
151
+ * Stripe.js quando presente. Ausente para cobranças síncronas/CNPJ. */
152
+ client_secret?: string | null;
153
+ /** PIX-LLC cross-currency: o cliente vê BRL (`presentment_*`) e a LLC escritura
154
+ * em USD (`currency`/`amount`); `exchange_rate` é o câmbio aplicado. */
155
+ presentment_currency?: Currency | null;
156
+ presentment_amount?: string | null;
157
+ exchange_rate?: string | null;
109
158
  installments: number;
110
159
  status: TransactionStatus;
111
160
  pix_qr_code?: string;
@@ -496,4 +545,4 @@ declare class Vitrin {
496
545
  request<T = unknown>(path: string, options?: Parameters<VitrinClient['request']>[1]): Promise<T>;
497
546
  }
498
547
 
499
- 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 };
548
+ 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 CHANGED
@@ -43,8 +43,42 @@ declare class VitrinClient {
43
43
  * Mantidos como interfaces genéricas (em vez de unions super-precisas) pra
44
44
  * que mudanças não-quebra-API no backend não exijam major bump no SDK.
45
45
  */
46
- type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD';
46
+ /** ISO 4217. BRL é o default histórico; USD/EUR/GBP habilitados com orgs LLC. */
47
+ type Currency = 'BRL' | 'USD' | 'EUR' | 'GBP';
48
+ /** Tipo jurídico da organização. CNPJ = subconta Safe2Pay (Brasil),
49
+ * LLC = Stripe Connect (US/internacional). */
50
+ type EntityType = 'cnpj' | 'llc';
51
+ /**
52
+ * Métodos de pagamento suportados pela plataforma.
53
+ *
54
+ * A disponibilidade por org é dinâmica — sempre cheque
55
+ * `Organization.enabled_payment_methods`. Por tipo de entidade:
56
+ *
57
+ * - CNPJ (BR): PIX, PIX_AUTOMATIC, BOLETO, CREDIT_CARD (default).
58
+ * - LLC (US): CREDIT_CARD por default. PIX está disponível cross-border
59
+ * (o cliente paga em BRL, a liquidação é em USD) como opt-in habilitado
60
+ * pela Vitrin. BOLETO NÃO se aplica a LLC (é Brasil-only). Os demais
61
+ * métodos abaixo (cartão internacional / ACH / wallets / Klarna /
62
+ * Afterpay) são reservados para evolução e podem não estar habilitados.
63
+ */
64
+ type PaymentMethod = 'PIX' | 'PIX_AUTOMATIC' | 'BOLETO' | 'CREDIT_CARD' | 'CARD_INTERNATIONAL' | 'ACH_DEBIT' | 'SEPA_DEBIT' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'KLARNA' | 'AFTERPAY';
47
65
  type TransactionStatus = 'pending' | 'confirmed' | 'received' | 'overdue' | 'refunded' | 'chargeback' | 'failed' | 'canceled';
66
+ /**
67
+ * Representa a organização (subconta) dona da API key em uso.
68
+ *
69
+ * Nota: `default_currency` é derivado de `entity_type` no backend e pode
70
+ * ainda não estar exposto pelo serializer — a declaração aqui é
71
+ * forward-compatible para quando o backend passar a emiti-lo.
72
+ */
73
+ interface Organization {
74
+ id: string;
75
+ name: string;
76
+ entity_type: EntityType;
77
+ default_currency: Currency;
78
+ enabled_payment_methods?: PaymentMethod[];
79
+ created_at: string;
80
+ updated_at: string;
81
+ }
48
82
  interface Customer {
49
83
  id: string;
50
84
  name: string;
@@ -94,6 +128,11 @@ interface Subscription {
94
128
  canceled_at: string | null;
95
129
  created_at: string;
96
130
  updated_at: string;
131
+ /** LLC: moeda da assinatura (USD). Ausente/BRL para CNPJ. */
132
+ currency?: Currency;
133
+ /** LLC: secret de confirmação da 1ª cobrança — quando presente, confirme
134
+ * com Stripe.js (cartão/SCA) antes da assinatura ficar ativa. */
135
+ client_secret?: string | null;
97
136
  }
98
137
  interface Transaction {
99
138
  id: string;
@@ -106,6 +145,16 @@ interface Transaction {
106
145
  platform_fee: string;
107
146
  provider_fee: string;
108
147
  billing_type: PaymentMethod;
148
+ /** ISO 4217. Default herdado de `Organization.default_currency` na criação. */
149
+ currency: Currency;
150
+ /** LLC: secret de confirmação — cartão (SCA/3DS) ou PIX (QR); confirme com
151
+ * Stripe.js quando presente. Ausente para cobranças síncronas/CNPJ. */
152
+ client_secret?: string | null;
153
+ /** PIX-LLC cross-currency: o cliente vê BRL (`presentment_*`) e a LLC escritura
154
+ * em USD (`currency`/`amount`); `exchange_rate` é o câmbio aplicado. */
155
+ presentment_currency?: Currency | null;
156
+ presentment_amount?: string | null;
157
+ exchange_rate?: string | null;
109
158
  installments: number;
110
159
  status: TransactionStatus;
111
160
  pix_qr_code?: string;
@@ -496,4 +545,4 @@ declare class Vitrin {
496
545
  request<T = unknown>(path: string, options?: Parameters<VitrinClient['request']>[1]): Promise<T>;
497
546
  }
498
547
 
499
- 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 };
548
+ 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vitrindigital/node",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "SDK oficial Node.js para a API da Vitrin Digital",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",