@vitrindigital/node 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,428 @@
+/**
+ * HTTP client interno do SDK.
+ *
+ * Responsabilidades:
+ *   - Adicionar headers padrão (Authorization, User-Agent, Content-Type)
+ *   - Serializar/deserializar JSON
+ *   - Mapear erros HTTP pra `VitrinError`*
+ *   - Retry automático em 429 e 5xx (até 3 tentativas, backoff exponencial)
+ *   - Idempotency-Key opcional pra POSTs (evita duplo-débito quando o cliente
+ *     retenta uma chamada que já chegou no servidor)
+ */
+interface VitrinClientOptions {
+    /** Chave da API (vd_test_* ou vd_live_*). */
+    apiKey: string;
+    /** Override da URL base. Default: https://api.vitrin.digital/api/v1 */
+    baseUrl?: string;
+    /** Timeout por request em ms. Default: 30000 (30s). */
+    timeout?: number;
+    /** Max retries em 429/5xx. Default: 3. */
+    maxRetries?: number;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    /** Idempotency-Key — recomendado em POSTs com efeito (criar charge, etc). */
+    idempotencyKey?: string;
+}
+declare class VitrinClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(opts: VitrinClientOptions);
+    /** Helper público pra resources. */
+    request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    private buildUrl;
+}
+
+/**
+ * Tipos compartilhados. Refletem os JSONs retornados pela API.
+ *
+ * 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';
+type TransactionStatus = 'pending' | 'confirmed' | 'received' | 'overdue' | 'refunded' | 'chargeback' | 'failed' | 'canceled';
+interface Customer {
+    id: string;
+    name: string;
+    email: string;
+    cpf_cnpj: string;
+    phone?: string;
+    address?: string;
+    address_number?: string;
+    province?: string;
+    postal_code?: string;
+    city?: string;
+    state?: string;
+    provider_customer_id?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface Plan {
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
+    price: string;
+    billing_cycle: 'weekly' | 'biweekly' | 'monthly' | 'bimonthly' | 'quarterly' | 'semiannually' | 'yearly';
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
+    price: string;
+    product_type: 'one_time' | 'pack' | 'credits';
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface Subscription {
+    id: string;
+    customer: string;
+    plan: string;
+    status: 'pending' | 'active' | 'overdue' | 'canceled' | 'expired';
+    billing_type: PaymentMethod;
+    current_period_start: string | null;
+    current_period_end: string | null;
+    canceled_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface Transaction {
+    id: string;
+    customer: string;
+    subscription: string | null;
+    provider_payment_id: string;
+    description: string;
+    amount: string;
+    net_amount: string;
+    platform_fee: string;
+    provider_fee: string;
+    billing_type: PaymentMethod;
+    installments: number;
+    status: TransactionStatus;
+    pix_qr_code?: string;
+    pix_copy_paste?: string;
+    boleto_url?: string;
+    boleto_barcode?: string;
+    due_date?: string | null;
+    paid_at?: string | null;
+    refunded_at?: string | null;
+    anticipated: boolean;
+    anticipation_fee: string;
+    created_at: string;
+    updated_at: string;
+}
+interface PaginatedList<T> {
+    count: number;
+    next: string | null;
+    previous: string | null;
+    results: T[];
+}
+/** Response do GET /balance/. */
+interface Balance {
+    available: number;
+    total: number;
+    pending: number;
+    withdrawal_fees: {
+        pix: number;
+        ted: number;
+    };
+}
+/** Response do GET /balance/scheduled/. */
+interface ScheduledReceivable {
+    release_date: string;
+    amount: number;
+    method: PaymentMethod;
+    installment: string | null;
+    transaction_id: string;
+    anticipated: boolean;
+}
+interface ScheduledReceivablesResponse {
+    horizon_days: number;
+    total_scheduled: number;
+    count: number;
+    by_day: Array<{
+        date: string;
+        total: number;
+        count: number;
+    }>;
+    items: ScheduledReceivable[];
+}
+
+interface CreateChargeParams {
+    customer_id: string;
+    amount: number | string;
+    billing_type: 'PIX' | 'BOLETO' | 'CREDIT_CARD';
+    description?: string;
+    due_date?: string;
+    installments?: number;
+    credit_card_token?: 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;
+    pin: string;
+}
+interface ListChargesParams {
+    status?: string;
+    billing_type?: string;
+    customer_id?: string;
+    date_from?: string;
+    date_to?: string;
+    min_amount?: number;
+    max_amount?: number;
+    page?: number;
+}
+declare class Charges {
+    private client;
+    constructor(client: VitrinClient);
+    /** Cria uma cobrança avulsa (PIX/Boleto/Cartão). */
+    create(params: CreateChargeParams): Promise<Transaction>;
+    retrieve(id: string): Promise<Transaction>;
+    list(params?: ListChargesParams): Promise<PaginatedList<Transaction>>;
+    refund(id: string, params: RefundParams): Promise<Transaction>;
+    cancel(id: string, pin: string): Promise<{
+        status: string;
+    }>;
+    /** Status atual da transação (consultado no provedor). */
+    status(id: string): Promise<{
+        status: string;
+        raw?: unknown;
+    }>;
+}
+
+interface CreateCustomerParams {
+    name: string;
+    email: string;
+    cpf_cnpj: string;
+    phone?: string;
+    address?: string;
+    address_number?: string;
+    province?: string;
+    postal_code?: string;
+    city?: string;
+    state?: string;
+}
+type UpdateCustomerParams = Partial<CreateCustomerParams>;
+declare class Customers {
+    private client;
+    constructor(client: VitrinClient);
+    create(params: CreateCustomerParams): Promise<Customer>;
+    retrieve(id: string): Promise<Customer>;
+    list(params?: {
+        page?: number;
+        search?: string;
+    }): Promise<PaginatedList<Customer>>;
+    update(id: string, params: UpdateCustomerParams): Promise<Customer>;
+    delete(id: string): Promise<void>;
+}
+
+interface CreatePlanParams {
+    name: string;
+    description?: string;
+    price: number | string;
+    billing_cycle: Plan['billing_cycle'];
+}
+type UpdatePlanParams = Partial<CreatePlanParams> & {
+    is_active?: boolean;
+};
+declare class Plans {
+    private client;
+    constructor(client: VitrinClient);
+    create(params: CreatePlanParams): Promise<Plan>;
+    retrieve(id: string): Promise<Plan>;
+    list(params?: {
+        page?: number;
+    }): Promise<PaginatedList<Plan>>;
+    update(id: string, params: UpdatePlanParams): Promise<Plan>;
+    delete(id: string): Promise<void>;
+}
+
+interface CreateSubscriptionParams {
+    customer_id: string;
+    plan_id: string;
+    billing_type: 'PIX' | 'CREDIT_CARD' | 'BOLETO';
+    credit_card_token?: string;
+    next_due_date?: string;
+}
+declare class Subscriptions {
+    private client;
+    constructor(client: VitrinClient);
+    create(params: CreateSubscriptionParams): Promise<Subscription>;
+    retrieve(id: string): Promise<Subscription>;
+    list(params?: {
+        page?: number;
+        status?: string;
+    }): Promise<PaginatedList<Subscription>>;
+    cancel(id: string, pin: string): Promise<Subscription>;
+}
+
+interface CreateProductParams {
+    name: string;
+    description?: string;
+    price: number | string;
+    product_type?: 'one_time' | 'pack' | 'credits';
+}
+type UpdateProductParams = Partial<CreateProductParams> & {
+    is_active?: boolean;
+};
+declare class Products {
+    private client;
+    constructor(client: VitrinClient);
+    create(params: CreateProductParams): Promise<Product>;
+    retrieve(id: string): Promise<Product>;
+    list(params?: {
+        page?: number;
+    }): Promise<PaginatedList<Product>>;
+    update(id: string, params: UpdateProductParams): Promise<Product>;
+    delete(id: string): Promise<void>;
+}
+
+declare class BalanceAPI {
+    private client;
+    constructor(client: VitrinClient);
+    /** Saldo atual: disponível, pendente e total. */
+    retrieve(): Promise<Balance>;
+    /** Cronograma de recebíveis futuros (Pix D+1, Boleto D+2, Cartão D+30·N). */
+    scheduled(daysAhead?: number): Promise<ScheduledReceivablesResponse>;
+}
+
+/**
+ * Validação de webhooks Vitrin → seu backend.
+ *
+ * Toda chamada que a Vitrin faz pra sua URL de webhook leva:
+ *   X-Vitrin-Signature: HMAC-SHA256 do body cru com `webhook_secret`
+ *   X-Vitrin-Timestamp: epoch UTC em segundos
+ *   X-Vitrin-Event:     tipo do evento (ex: "Autorizado")
+ *   X-Vitrin-Event-Id:  ID único pra idempotência
+ *
+ * Use `Webhooks.constructEvent` no handler do seu backend pra validar
+ * antes de processar — protege contra requisições forjadas.
+ */
+interface WebhookEvent<T = Record<string, unknown>> {
+    /** Tipo do evento (ex: "Autorizado", "Estornado"). */
+    type: string;
+    /** ID único do evento (use pra idempotência). */
+    id: string;
+    /** Timestamp em ms da epoch UTC. */
+    timestampMs: number;
+    /** Payload original já parseado. */
+    data: T;
+}
+interface ConstructEventOptions {
+    /** Body cru (string ou Buffer) recebido — NÃO o objeto parseado. */
+    payload: string | Buffer;
+    /** Header X-Vitrin-Signature. */
+    signature: string | null | undefined;
+    /** Header X-Vitrin-Timestamp (segundos). */
+    timestamp?: string | null | undefined;
+    /** Header X-Vitrin-Event. */
+    eventType?: string | null | undefined;
+    /** Header X-Vitrin-Event-Id. */
+    eventId?: string | null | undefined;
+    /** Webhook secret da org (org.webhook_secret no nosso backend). */
+    secret: string;
+    /** Tolerância de timestamp (ms) — rejeita se headers vierem stale.
+     *  Default: 5 minutos. Passe 0 pra desabilitar. */
+    toleranceMs?: number;
+}
+declare const Webhooks: {
+    /** Valida a assinatura e retorna o evento parseado. Lança em qualquer falha. */
+    constructEvent<T = Record<string, unknown>>(opts: ConstructEventOptions): WebhookEvent<T>;
+};
+
+/**
+ * Hierarquia de erros do SDK. Todos descendem de `VitrinError`.
+ *
+ *   VitrinError                      — base, qualquer falha conhecida do SDK
+ *     ├─ VitrinAuthError             — 401/403 (chave inválida ou sem permissão)
+ *     ├─ VitrinValidationError       — 400/422 (DRF retornou field errors)
+ *     ├─ VitrinRateLimitError        — 429
+ *     ├─ VitrinNotFoundError         — 404
+ *     ├─ VitrinServerError           — 5xx
+ *     └─ VitrinNetworkError          — falha antes da resposta (DNS, timeout...)
+ *
+ * Toda instância carrega `statusCode`, `body` (resposta crua) e `requestId`
+ * (header X-Request-ID se presente) pra logging.
+ */
+declare class VitrinError extends Error {
+    readonly statusCode?: number;
+    readonly body?: unknown;
+    readonly requestId?: string;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        body?: unknown;
+        requestId?: string;
+    });
+}
+declare class VitrinAuthError extends VitrinError {
+}
+declare class VitrinValidationError extends VitrinError {
+    readonly fieldErrors?: Record<string, string[]>;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        body?: unknown;
+        requestId?: string;
+        fieldErrors?: Record<string, string[]>;
+    });
+}
+declare class VitrinRateLimitError extends VitrinError {
+}
+declare class VitrinNotFoundError extends VitrinError {
+}
+declare class VitrinServerError extends VitrinError {
+}
+declare class VitrinNetworkError extends VitrinError {
+}
+
+/**
+ * @vitrindigital/node — SDK oficial Node.js da Vitrin Digital.
+ *
+ * @example
+ * ```ts
+ * import { Vitrin } from '@vitrindigital/node';
+ *
+ * const vitrin = new Vitrin({ apiKey: process.env.VITRIN_API_KEY! });
+ *
+ * const customer = await vitrin.customers.create({
+ *   name: 'Maria Silva',
+ *   email: 'maria@test.com',
+ *   cpf_cnpj: '12345678901',
+ * });
+ *
+ * const charge = await vitrin.charges.create({
+ *   customer_id: customer.id,
+ *   amount: 99.90,
+ *   billing_type: 'PIX',
+ *   description: 'Mensalidade abril',
+ *   idempotencyKey: `mensalidade-${customer.id}-2026-04`,
+ * });
+ *
+ * console.log(charge.pix_qr_code);
+ * ```
+ */
+
+declare class Vitrin {
+    readonly client: VitrinClient;
+    readonly charges: Charges;
+    readonly customers: Customers;
+    readonly plans: Plans;
+    readonly subscriptions: Subscriptions;
+    readonly products: Products;
+    readonly balance: BalanceAPI;
+    constructor(opts: VitrinClientOptions);
+    /** Acesso bruto pro caso de endpoint não coberto pelos resources. */
+    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 };