@garuhq/node 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,393 @@
+import createClient from 'openapi-fetch';
+
+interface VerifyWebhookParams {
+    /** Raw request body as received — do NOT re-serialize parsed JSON. */
+    payload: string | Buffer;
+    /** Value of the `X-Garu-Signature` header. Format: `t=<ts>,v1=<hex>`. */
+    signature: string;
+    /** The webhook endpoint's signing secret. */
+    secret: string;
+    /** Reject signatures older than this many seconds. Default: 300 (5 min). */
+    toleranceSec?: number;
+    /** Injectable for tests. Defaults to `Date.now()`. */
+    now?: () => number;
+}
+interface VerifiedWebhook {
+    /** Timestamp from the signature header, in seconds since epoch. */
+    timestamp: number;
+    /** Parsed JSON body. Throws {@link GaruSignatureVerificationError} if invalid JSON. */
+    event: unknown;
+}
+/**
+ * Webhook helpers.
+ *
+ * Garu signs outgoing webhooks with HMAC-SHA256 over `${timestamp}.${payload}`
+ * and delivers the signature in the `X-Garu-Signature` header as `t=<ts>,v1=<hex>`.
+ * This matches the format in the backend's `webhook-delivery.service.ts`.
+ *
+ * @example
+ * // Express example
+ * app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     const { event } = Garu.webhooks.verify({
+ *       payload: req.body,
+ *       signature: req.header('x-garu-signature') ?? '',
+ *       secret: process.env.GARU_WEBHOOK_SECRET!
+ *     });
+ *     // handle event
+ *     res.sendStatus(200);
+ *   } catch (err) {
+ *     res.sendStatus(400);
+ *   }
+ * });
+ */
+declare const webhooks: {
+    verify(params: VerifyWebhookParams): VerifiedWebhook;
+};
+
+interface HttpClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    timeoutMs: number;
+    maxRetries: number;
+    userAgent: string;
+    /** Injectable for tests. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/** Typed openapi-fetch client keyed to the backend's OpenAPI paths. */
+type GaruOpenapiClient = ReturnType<typeof createClient<paths>>;
+/** Arg type for `HttpClient.call` — a thunk that issues one openapi-fetch request. */
+type OpenapiCallResult<T> = Promise<{
+    data?: T;
+    error?: unknown;
+    response: Response;
+}>;
+/**
+ * HttpClient wraps the generated `openapi-fetch` client with:
+ *   - retries (exponential backoff, full jitter, honors `Retry-After`)
+ *   - typed error mapping (non-2xx → {@link GaruAPIError} subclass)
+ *   - connection error wrapping
+ *   - Authorization + User-Agent injection
+ *
+ * Resources call {@link call} with a thunk that returns an openapi-fetch
+ * `{ data, error, response }` tuple; the wrapper either returns `data` or
+ * throws the mapped error.
+ */
+declare class HttpClient {
+    readonly client: GaruOpenapiClient;
+    private readonly cfg;
+    constructor(cfg: HttpClientConfig);
+    /**
+     * Issue one HTTP call against the typed client, with retries + error mapping.
+     *
+     * `fn` is invoked up to `maxRetries + 1` times. The timeout in `cfg.timeoutMs`
+     * is enforced via `AbortController`.
+     */
+    call<T>(fn: (signal: AbortSignal) => OpenapiCallResult<T>): Promise<T>;
+}
+
+/**
+ * Public types for the Garu SDK.
+ *
+ * The wire-level types (`WireCreateTransactionRequest`, `WireMetaResponse`, ...)
+ * are generated from the backend's OpenAPI spec and live in
+ * `src/generated/schema.d.ts`. The friendly types in this file
+ * (`CreateChargeParams`, `Customer`, `Charge`, ...) are hand-curated for
+ * ergonomics — they rename `transactions` to `charges`, collapse wire enums
+ * into readable unions, and mark only truly required fields as required.
+ * The resource layer maps friendly → wire at the edge.
+ */
+
+type PaymentMethod = 'pix' | 'credit_card' | 'boleto';
+/** Payment-method identifier as sent to the backend over the wire. */
+type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto';
+type ChargeStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'refunded' | 'cancelled' | 'expired';
+interface Customer {
+    /** Full legal name. 3–255 chars. */
+    name: string;
+    email: string;
+    /** CPF (11 digits) or CNPJ (14 digits), digits only. */
+    document: string;
+    /** 10 or 11 digits with area code, no formatting. */
+    phone: string;
+    /** 8 digits, no hyphen. Optional. */
+    zipCode?: string;
+    street?: string;
+    number?: string;
+    complement?: string;
+    neighborhood?: string;
+    city?: string;
+    /** 2-letter uppercase state code, e.g. `SP`. */
+    state?: string;
+}
+interface CardInfo {
+    /** 13–19 digits, no spaces or hyphens. */
+    cardNumber: string;
+    /** 3 or 4 digits. */
+    cvv: string;
+    /** `YYYY-MM`. */
+    expirationDate: string;
+    /** As printed on the card. */
+    holderName: string;
+    /** 1–12. */
+    installments: number;
+}
+interface CreateChargeParams {
+    /** Customer buying the product. */
+    customer: Customer;
+    /** UUID of the product being charged. */
+    productId: string;
+    /** Payment method. */
+    paymentMethod: PaymentMethod;
+    /** Required when `paymentMethod` is `credit_card`. */
+    cardInfo?: CardInfo;
+    /** Free-form metadata attached to the charge. */
+    additionalInfo?: string;
+    /** Original checkout link, if any. */
+    link?: string | null;
+    /** Associated affiliate ID, if any. */
+    affiliateId?: number | null;
+    /** Subscription price ID (`price_*`), for subscription charges only. */
+    priceId?: string | null;
+    /** Optional pre-created checkout session token. */
+    checkoutSessionToken?: string;
+    /**
+     * Idempotency key. If omitted, the SDK generates a UUIDv4.
+     * Keys are valid for 24h on the backend.
+     */
+    idempotencyKey?: string;
+}
+interface Charge {
+    id: number;
+    status: ChargeStatus;
+    amount: number;
+    paymentMethodId: WirePaymentMethodId;
+    /** ISO-8601. */
+    date: string;
+    /** ISO-8601. */
+    deadline?: string;
+    /** Product this charge belongs to. */
+    product?: {
+        id: number;
+        uuid?: string;
+        name?: string;
+    };
+    [key: string]: unknown;
+}
+interface RefundChargeParams {
+    /** Partial refund in centavos. Omit for full refund. */
+    amount?: number;
+    /** Free-form reason stored on the refund. */
+    reason?: string;
+    idempotencyKey?: string;
+}
+interface MetaFeatures {
+    subscriptions: boolean;
+    checkout_sessions: boolean;
+    idempotency_keys: boolean;
+    test_mode: boolean;
+    webhooks: boolean;
+}
+interface MetaResponse {
+    name: string;
+    version: string;
+    environment: 'production' | 'staging' | 'development' | string;
+    api_version: string;
+    payment_methods: string[];
+    currencies: string[];
+    billing_intervals: string[];
+    webhook_events: string[];
+    features: MetaFeatures;
+    docs_url: string;
+    dashboard_url: string;
+    support_email: string;
+}
+
+/**
+ * Charges — the core of the Garu API.
+ *
+ * A charge represents a single payment attempt against a product. The SDK
+ * surfaces charges under `garu.charges` even though the backend route is
+ * `/api/transactions` — this matches Stripe convention and is the name every
+ * other Garu surface (MCP, CLI, docs) uses.
+ */
+declare class Charges {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a charge (PIX, credit card, or boleto).
+     *
+     * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the backend
+     * caches the first response for 24h.
+     *
+     * @example
+     * // PIX charge
+     * const charge = await garu.charges.create({
+     *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+     *   paymentMethod: 'pix',
+     *   customer: {
+     *     name: 'Maria Silva',
+     *     email: 'maria@exemplo.com.br',
+     *     document: '12345678909',
+     *     phone: '11987654321'
+     *   }
+     * });
+     * console.log(charge.id, charge.status);
+     *
+     * @example
+     * // Credit card charge, 3 installments
+     * const charge = await garu.charges.create({
+     *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+     *   paymentMethod: 'credit_card',
+     *   customer: { name: 'Maria Silva', email: 'maria@exemplo.com.br', document: '12345678909', phone: '11987654321' },
+     *   cardInfo: {
+     *     cardNumber: '4111111111111111',
+     *     cvv: '123',
+     *     expirationDate: '2030-12',
+     *     holderName: 'MARIA SILVA',
+     *     installments: 3
+     *   }
+     * });
+     */
+    create(params: CreateChargeParams): Promise<Charge>;
+    /**
+     * Fetch a single charge by numeric ID.
+     *
+     * @example
+     * const charge = await garu.charges.get(4472);
+     * if (charge.status === 'paid') { ... }
+     */
+    get(id: number): Promise<Charge>;
+    /**
+     * Refund a charge — fully, or partially by passing `amount` in centavos.
+     *
+     * @example
+     * // Full refund
+     * await garu.charges.refund(4472);
+     *
+     * @example
+     * // Partial refund of R$ 10,00
+     * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });
+     */
+    refund(id: number, params?: RefundChargeParams): Promise<Charge>;
+    private buildCreateBody;
+}
+
+/**
+ * Meta — capability introspection.
+ *
+ * Unauthenticated. Used by `garu doctor`, MCP tool `doctor`, and by SDK
+ * consumers that want to know which payment methods and webhook events are
+ * currently supported.
+ */
+declare class Meta {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Fetch the API's current capability payload.
+     *
+     * @example
+     * const meta = await garu.meta.get();
+     * console.log(meta.version, meta.payment_methods);
+     * if (meta.features.subscriptions) { ... }
+     */
+    get(): Promise<MetaResponse>;
+}
+
+interface GaruOptions {
+    /**
+     * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
+     * Optional — public endpoints (`meta.get`, public charge creation) work without one.
+     */
+    apiKey?: string;
+    /** Override the API base URL. Default: `https://garu.com.br/api`. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default: 30000. */
+    timeoutMs?: number;
+    /** Max retries on retryable errors (connection, 408, 429, 5xx). Default: 2. */
+    maxRetries?: number;
+    /** Injectable for tests. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * The Garu SDK client.
+ *
+ * @example
+ * import { Garu } from '@garuhq/node';
+ *
+ * const garu = new Garu({ apiKey: process.env.GARU_API_KEY });
+ *
+ * const charge = await garu.charges.create({
+ *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+ *   paymentMethod: 'pix',
+ *   customer: {
+ *     name: 'Maria Silva',
+ *     email: 'maria@exemplo.com.br',
+ *     document: '12345678909',
+ *     phone: '11987654321'
+ *   }
+ * });
+ */
+declare class Garu {
+    readonly charges: Charges;
+    readonly meta: Meta;
+    /**
+     * Webhook helpers. Available both as an instance member and as a static —
+     * `Garu.webhooks.verify(...)` works without constructing a client.
+     */
+    static readonly webhooks: {
+        verify(params: VerifyWebhookParams): VerifiedWebhook;
+    };
+    readonly webhooks: {
+        verify(params: VerifyWebhookParams): VerifiedWebhook;
+    };
+    constructor(options?: GaruOptions);
+}
+
+/**
+ * Error hierarchy for the Garu SDK.
+ *
+ * Every error has a stable `code` string so agents and typed clients can switch on it
+ * without parsing messages. Non-2xx API responses are mapped to the most specific
+ * subclass of `GaruAPIError` by {@link mapApiError}.
+ */
+type GaruErrorCode = 'authentication_error' | 'permission_error' | 'not_found' | 'validation_error' | 'rate_limited' | 'server_error' | 'api_error' | 'connection_error' | 'signature_verification_failed';
+declare class GaruError extends Error {
+    readonly code: GaruErrorCode;
+    constructor(code: GaruErrorCode, message: string);
+}
+declare class GaruConnectionError extends GaruError {
+    readonly connectionCause: unknown;
+    constructor(message: string, connectionCause?: unknown);
+}
+declare class GaruSignatureVerificationError extends GaruError {
+    constructor(message: string);
+}
+declare class GaruAPIError extends GaruError {
+    readonly status: number;
+    readonly requestId: string | null;
+    readonly body: unknown;
+    constructor(code: GaruErrorCode, message: string, status: number, requestId: string | null, body: unknown);
+}
+declare class GaruAuthenticationError extends GaruAPIError {
+    constructor(message: string, status: number, requestId: string | null, body: unknown);
+}
+declare class GaruPermissionError extends GaruAPIError {
+    constructor(message: string, status: number, requestId: string | null, body: unknown);
+}
+declare class GaruNotFoundError extends GaruAPIError {
+    constructor(message: string, status: number, requestId: string | null, body: unknown);
+}
+declare class GaruValidationError extends GaruAPIError {
+    constructor(message: string, status: number, requestId: string | null, body: unknown);
+}
+declare class GaruRateLimitError extends GaruAPIError {
+    readonly retryAfterSec: number | null;
+    constructor(message: string, status: number, requestId: string | null, body: unknown, retryAfterSec: number | null);
+}
+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 };