@garuhq/node 0.1.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/http.ts","../src/errors.ts","../src/idempotency.ts","../src/types.ts","../src/resources/charges.ts","../src/resources/meta.ts","../src/webhooks.ts","../src/client.ts"],"names":[],"mappings":"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","sourcesContent":["import createClient from 'openapi-fetch';\n\nimport { GaruConnectionError, mapApiError, type GaruAPIError } from './errors.js';\nimport type { paths } from './generated/schema.js';\n\nexport interface HttpClientConfig {\n  baseUrl: string;\n  apiKey?: string;\n  timeoutMs: number;\n  maxRetries: number;\n  userAgent: string;\n  /** Injectable for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n}\n\nconst RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);\n\n/** Typed openapi-fetch client keyed to the backend's OpenAPI paths. */\nexport type GaruOpenapiClient = ReturnType<typeof createClient<paths>>;\n\n/** Arg type for `HttpClient.call` — a thunk that issues one openapi-fetch request. */\nexport type OpenapiCallResult<T> = Promise<{\n  data?: T;\n  error?: unknown;\n  response: Response;\n}>;\n\n/**\n * HttpClient wraps the generated `openapi-fetch` client with:\n *   - retries (exponential backoff, full jitter, honors `Retry-After`)\n *   - typed error mapping (non-2xx → {@link GaruAPIError} subclass)\n *   - connection error wrapping\n *   - Authorization + User-Agent injection\n *\n * Resources call {@link call} with a thunk that returns an openapi-fetch\n * `{ data, error, response }` tuple; the wrapper either returns `data` or\n * throws the mapped error.\n */\nexport class HttpClient {\n  public readonly client: GaruOpenapiClient;\n  private readonly cfg: HttpClientConfig;\n\n  constructor(cfg: HttpClientConfig) {\n    this.cfg = cfg;\n    const fetchImpl = cfg.fetch ?? globalThis.fetch;\n    if (!fetchImpl) {\n      throw new GaruConnectionError(\n        'No fetch implementation available. Node.js >= 18 is required.'\n      );\n    }\n    const headers: Record<string, string> = {\n      Accept: 'application/json',\n      'User-Agent': cfg.userAgent\n    };\n    if (cfg.apiKey) headers.Authorization = `Bearer ${cfg.apiKey}`;\n\n    this.client = createClient<paths>({\n      baseUrl: cfg.baseUrl.replace(/\\/+$/, ''),\n      fetch: fetchImpl,\n      headers\n    });\n  }\n\n  /**\n   * Issue one HTTP call against the typed client, with retries + error mapping.\n   *\n   * `fn` is invoked up to `maxRetries + 1` times. The timeout in `cfg.timeoutMs`\n   * is enforced via `AbortController`.\n   */\n  async call<T>(fn: (signal: AbortSignal) => OpenapiCallResult<T>): Promise<T> {\n    let lastError: GaruAPIError | GaruConnectionError | null = null;\n\n    for (let attempt = 0; attempt <= this.cfg.maxRetries; attempt++) {\n      const controller = new AbortController();\n      const timer = setTimeout(() => controller.abort(), this.cfg.timeoutMs);\n\n      try {\n        const { data, error, response } = await fn(controller.signal);\n        clearTimeout(timer);\n\n        if (response.ok) {\n          return data as T;\n        }\n\n        const requestId = response.headers.get('x-request-id');\n        const retryAfterSec = parseRetryAfter(response.headers.get('retry-after'));\n        const apiError = mapApiError(response.status, error ?? null, requestId, retryAfterSec);\n        lastError = apiError;\n\n        if (!RETRYABLE_STATUSES.has(response.status) || attempt === this.cfg.maxRetries) {\n          throw apiError;\n        }\n\n        await sleep(backoffDelay(attempt, retryAfterSec));\n        continue;\n      } catch (err) {\n        clearTimeout(timer);\n\n        if (isGaruApiError(err)) throw err;\n\n        const connErr =\n          err instanceof Error && err.name === 'AbortError'\n            ? new GaruConnectionError(`Request timed out after ${this.cfg.timeoutMs}ms`, err)\n            : new GaruConnectionError(err instanceof Error ? err.message : 'Network error', err);\n        lastError = connErr;\n\n        if (attempt === this.cfg.maxRetries) throw connErr;\n        await sleep(backoffDelay(attempt, null));\n        continue;\n      }\n    }\n\n    // Unreachable — the loop always throws or returns on the final attempt.\n    throw lastError ?? new GaruConnectionError('Request failed with no error captured');\n  }\n}\n\nfunction isGaruApiError(err: unknown): boolean {\n  return err instanceof Error && err.name.startsWith('Garu') && err.name.endsWith('Error');\n}\n\nfunction parseRetryAfter(value: string | null): number | null {\n  if (!value) return null;\n  const n = Number(value);\n  return Number.isFinite(n) && n >= 0 ? n : null;\n}\n\n/**\n * Exponential backoff with full jitter. If the server returned `Retry-After`,\n * we honor it (with a small jitter).\n */\nfunction backoffDelay(attempt: number, retryAfterSec: number | null): number {\n  if (retryAfterSec !== null) {\n    return retryAfterSec * 1000 + Math.random() * 250;\n  }\n  const base = 500 * 2 ** attempt;\n  const cap = 8000;\n  return Math.min(cap, base) * Math.random();\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n","/**\n * Error hierarchy for the Garu SDK.\n *\n * Every error has a stable `code` string so agents and typed clients can switch on it\n * without parsing messages. Non-2xx API responses are mapped to the most specific\n * subclass of `GaruAPIError` by {@link mapApiError}.\n */\n\nexport type GaruErrorCode =\n  | 'authentication_error'\n  | 'permission_error'\n  | 'not_found'\n  | 'validation_error'\n  | 'rate_limited'\n  | 'server_error'\n  | 'api_error'\n  | 'connection_error'\n  | 'signature_verification_failed';\n\nexport class GaruError extends Error {\n  public readonly code: GaruErrorCode;\n\n  constructor(code: GaruErrorCode, message: string) {\n    super(message);\n    this.name = 'GaruError';\n    this.code = code;\n  }\n}\n\nexport class GaruConnectionError extends GaruError {\n  public readonly connectionCause: unknown;\n  constructor(message: string, connectionCause?: unknown) {\n    super('connection_error', message);\n    this.name = 'GaruConnectionError';\n    this.connectionCause = connectionCause;\n  }\n}\n\nexport class GaruSignatureVerificationError extends GaruError {\n  constructor(message: string) {\n    super('signature_verification_failed', message);\n    this.name = 'GaruSignatureVerificationError';\n  }\n}\n\nexport class GaruAPIError extends GaruError {\n  public readonly status: number;\n  public readonly requestId: string | null;\n  public readonly body: unknown;\n\n  constructor(\n    code: GaruErrorCode,\n    message: string,\n    status: number,\n    requestId: string | null,\n    body: unknown\n  ) {\n    super(code, message);\n    this.name = 'GaruAPIError';\n    this.status = status;\n    this.requestId = requestId;\n    this.body = body;\n  }\n}\n\nexport class GaruAuthenticationError extends GaruAPIError {\n  constructor(message: string, status: number, requestId: string | null, body: unknown) {\n    super('authentication_error', message, status, requestId, body);\n    this.name = 'GaruAuthenticationError';\n  }\n}\n\nexport class GaruPermissionError extends GaruAPIError {\n  constructor(message: string, status: number, requestId: string | null, body: unknown) {\n    super('permission_error', message, status, requestId, body);\n    this.name = 'GaruPermissionError';\n  }\n}\n\nexport class GaruNotFoundError extends GaruAPIError {\n  constructor(message: string, status: number, requestId: string | null, body: unknown) {\n    super('not_found', message, status, requestId, body);\n    this.name = 'GaruNotFoundError';\n  }\n}\n\nexport class GaruValidationError extends GaruAPIError {\n  constructor(message: string, status: number, requestId: string | null, body: unknown) {\n    super('validation_error', message, status, requestId, body);\n    this.name = 'GaruValidationError';\n  }\n}\n\nexport class GaruRateLimitError extends GaruAPIError {\n  public readonly retryAfterSec: number | null;\n  constructor(\n    message: string,\n    status: number,\n    requestId: string | null,\n    body: unknown,\n    retryAfterSec: number | null\n  ) {\n    super('rate_limited', message, status, requestId, body);\n    this.name = 'GaruRateLimitError';\n    this.retryAfterSec = retryAfterSec;\n  }\n}\n\nexport class GaruServerError extends GaruAPIError {\n  constructor(message: string, status: number, requestId: string | null, body: unknown) {\n    super('server_error', message, status, requestId, body);\n    this.name = 'GaruServerError';\n  }\n}\n\n/**\n * Map a non-2xx HTTP response to the most specific {@link GaruAPIError} subclass.\n */\nexport function mapApiError(\n  status: number,\n  body: unknown,\n  requestId: string | null,\n  retryAfterSec: number | null\n): GaruAPIError {\n  const message = extractMessage(body) ?? `Garu API returned HTTP ${status}`;\n\n  if (status === 401) return new GaruAuthenticationError(message, status, requestId, body);\n  if (status === 403) return new GaruPermissionError(message, status, requestId, body);\n  if (status === 404) return new GaruNotFoundError(message, status, requestId, body);\n  if (status === 400 || status === 422) {\n    return new GaruValidationError(message, status, requestId, body);\n  }\n  if (status === 429) {\n    return new GaruRateLimitError(message, status, requestId, body, retryAfterSec);\n  }\n  if (status >= 500) return new GaruServerError(message, status, requestId, body);\n  return new GaruAPIError('api_error', message, status, requestId, body);\n}\n\nfunction extractMessage(body: unknown): string | null {\n  if (typeof body === 'string') return body;\n  if (body && typeof body === 'object') {\n    const m = (body as { message?: unknown }).message;\n    if (typeof m === 'string') return m;\n    if (Array.isArray(m) && m.every((x) => typeof x === 'string')) return m.join('; ');\n  }\n  return null;\n}\n","import { randomUUID } from 'node:crypto';\n\n/**\n * Generate a UUIDv4 suitable for use as an `X-Idempotency-Key` header value.\n *\n * @example\n * const key = generateIdempotencyKey();\n * // '3b241101-e2bb-4255-8caf-4136c566a962'\n */\nexport function generateIdempotencyKey(): string {\n  return randomUUID();\n}\n","/**\n * Public types for the Garu SDK.\n *\n * The wire-level types (`WireCreateTransactionRequest`, `WireMetaResponse`, ...)\n * are generated from the backend's OpenAPI spec and live in\n * `src/generated/schema.d.ts`. The friendly types in this file\n * (`CreateChargeParams`, `Customer`, `Charge`, ...) are hand-curated for\n * ergonomics — they rename `transactions` to `charges`, collapse wire enums\n * into readable unions, and mark only truly required fields as required.\n * The resource layer maps friendly → wire at the edge.\n */\n\nimport type { components } from './generated/schema.js';\n\nexport type WireCreateTransactionRequest = components['schemas']['CreateTransactionRequest'];\nexport type WireCustomerDto = components['schemas']['CustomerDto'];\nexport type WireCardInfoDto = components['schemas']['CardInfoDto'];\nexport type WireMetaResponse = components['schemas']['MetaResponse'];\n\nexport type PaymentMethod = 'pix' | 'credit_card' | 'boleto';\n\n/** Payment-method identifier as sent to the backend over the wire. */\nexport type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto';\n\nexport type ChargeStatus =\n  | 'pending'\n  | 'authorized'\n  | 'paid'\n  | 'failed'\n  | 'refunded'\n  | 'cancelled'\n  | 'expired';\n\nexport interface Customer {\n  /** Full legal name. 3–255 chars. */\n  name: string;\n  email: string;\n  /** CPF (11 digits) or CNPJ (14 digits), digits only. */\n  document: string;\n  /** 10 or 11 digits with area code, no formatting. */\n  phone: string;\n  /** 8 digits, no hyphen. Optional. */\n  zipCode?: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  /** 2-letter uppercase state code, e.g. `SP`. */\n  state?: string;\n}\n\nexport interface CardInfo {\n  /** 13–19 digits, no spaces or hyphens. */\n  cardNumber: string;\n  /** 3 or 4 digits. */\n  cvv: string;\n  /** `YYYY-MM`. */\n  expirationDate: string;\n  /** As printed on the card. */\n  holderName: string;\n  /** 1–12. */\n  installments: number;\n}\n\nexport interface CreateChargeParams {\n  /** Customer buying the product. */\n  customer: Customer;\n  /** UUID of the product being charged. */\n  productId: string;\n  /** Payment method. */\n  paymentMethod: PaymentMethod;\n  /** Required when `paymentMethod` is `credit_card`. */\n  cardInfo?: CardInfo;\n  /** Free-form metadata attached to the charge. */\n  additionalInfo?: string;\n  /** Original checkout link, if any. */\n  link?: string | null;\n  /** Associated affiliate ID, if any. */\n  affiliateId?: number | null;\n  /** Subscription price ID (`price_*`), for subscription charges only. */\n  priceId?: string | null;\n  /** Optional pre-created checkout session token. */\n  checkoutSessionToken?: string;\n  /**\n   * Idempotency key. If omitted, the SDK generates a UUIDv4.\n   * Keys are valid for 24h on the backend.\n   */\n  idempotencyKey?: string;\n}\n\nexport interface Charge {\n  id: number;\n  status: ChargeStatus;\n  amount: number;\n  paymentMethodId: WirePaymentMethodId;\n  /** ISO-8601. */\n  date: string;\n  /** ISO-8601. */\n  deadline?: string;\n  /** Product this charge belongs to. */\n  product?: { id: number; uuid?: string; name?: string };\n  [key: string]: unknown;\n}\n\nexport interface RefundChargeParams {\n  /** Partial refund in centavos. Omit for full refund. */\n  amount?: number;\n  /** Free-form reason stored on the refund. */\n  reason?: string;\n  idempotencyKey?: string;\n}\n\nexport interface MetaFeatures {\n  subscriptions: boolean;\n  checkout_sessions: boolean;\n  idempotency_keys: boolean;\n  test_mode: boolean;\n  webhooks: boolean;\n}\n\nexport interface MetaResponse {\n  name: string;\n  version: string;\n  environment: 'production' | 'staging' | 'development' | string;\n  api_version: string;\n  payment_methods: string[];\n  currencies: string[];\n  billing_intervals: string[];\n  webhook_events: string[];\n  features: MetaFeatures;\n  docs_url: string;\n  dashboard_url: string;\n  support_email: string;\n}\n\n/** Map the SDK's friendly `PaymentMethod` to the backend's wire value. */\nexport function toWirePaymentMethod(pm: PaymentMethod): WirePaymentMethodId {\n  return pm === 'credit_card' ? 'creditcard' : pm;\n}\n","import type { HttpClient } from '../http.js';\nimport type { components } from '../generated/schema.js';\nimport { generateIdempotencyKey } from '../idempotency.js';\nimport {\n  toWirePaymentMethod,\n  type Charge,\n  type CreateChargeParams,\n  type RefundChargeParams\n} from '../types.js';\n\ntype CreateTransactionBody = components['schemas']['CreateTransactionRequest'];\n\n/**\n * Charges — the core of the Garu API.\n *\n * A charge represents a single payment attempt against a product. The SDK\n * surfaces charges under `garu.charges` even though the backend route is\n * `/api/transactions` — this matches Stripe convention and is the name every\n * other Garu surface (MCP, CLI, docs) uses.\n */\nexport class Charges {\n  constructor(private readonly http: HttpClient) {}\n\n  /**\n   * Create a charge (PIX, credit card, or boleto).\n   *\n   * Automatically attaches an `X-Idempotency-Key` header — if you don't pass\n   * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the backend\n   * caches the first response for 24h.\n   *\n   * @example\n   * // PIX charge\n   * const charge = await garu.charges.create({\n   *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',\n   *   paymentMethod: 'pix',\n   *   customer: {\n   *     name: 'Maria Silva',\n   *     email: 'maria@exemplo.com.br',\n   *     document: '12345678909',\n   *     phone: '11987654321'\n   *   }\n   * });\n   * console.log(charge.id, charge.status);\n   *\n   * @example\n   * // Credit card charge, 3 installments\n   * const charge = await garu.charges.create({\n   *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',\n   *   paymentMethod: 'credit_card',\n   *   customer: { name: 'Maria Silva', email: 'maria@exemplo.com.br', document: '12345678909', phone: '11987654321' },\n   *   cardInfo: {\n   *     cardNumber: '4111111111111111',\n   *     cvv: '123',\n   *     expirationDate: '2030-12',\n   *     holderName: 'MARIA SILVA',\n   *     installments: 3\n   *   }\n   * });\n   */\n  async create(params: CreateChargeParams): Promise<Charge> {\n    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();\n    const body = this.buildCreateBody(params);\n\n    return this.http.call<Charge>(\n      (signal) =>\n        this.http.client.POST('/api/transactions', {\n          body,\n          headers: { 'X-Idempotency-Key': idempotencyKey },\n          signal\n        }) as Promise<{ data?: Charge; error?: unknown; response: Response }>\n    );\n  }\n\n  /**\n   * Fetch a single charge by numeric ID.\n   *\n   * @example\n   * const charge = await garu.charges.get(4472);\n   * if (charge.status === 'paid') { ... }\n   */\n  async get(id: number): Promise<Charge> {\n    return this.http.call<Charge>(\n      (signal) =>\n        this.http.client.GET('/api/transactions/{id}', {\n          params: { path: { id } },\n          signal\n        }) as Promise<{ data?: Charge; error?: unknown; response: Response }>\n    );\n  }\n\n  /**\n   * Refund a charge — fully, or partially by passing `amount` in centavos.\n   *\n   * @example\n   * // Full refund\n   * await garu.charges.refund(4472);\n   *\n   * @example\n   * // Partial refund of R$ 10,00\n   * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });\n   */\n  async refund(id: number, params: RefundChargeParams = {}): Promise<Charge> {\n    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();\n    const body: Record<string, unknown> = {};\n    if (params.amount !== undefined) body.amount = params.amount;\n    if (params.reason !== undefined) body.reason = params.reason;\n\n    return this.http.call<Charge>(\n      (signal) =>\n        this.http.client.POST('/api/transactions/{id}/refund', {\n          params: { path: { id } },\n          body: body as never,\n          headers: { 'X-Idempotency-Key': idempotencyKey },\n          signal\n        }) as Promise<{ data?: Charge; error?: unknown; response: Response }>\n    );\n  }\n\n  private buildCreateBody(params: CreateChargeParams): CreateTransactionBody {\n    const body: Record<string, unknown> = {\n      customer: params.customer,\n      productId: params.productId,\n      paymentMethodId: toWirePaymentMethod(params.paymentMethod),\n      link: params.link ?? null,\n      affiliateId: params.affiliateId ?? null\n    };\n    if (params.additionalInfo !== undefined) body.additionalInfo = params.additionalInfo;\n    if (params.priceId !== undefined) body.priceId = params.priceId;\n    if (params.checkoutSessionToken !== undefined) {\n      body.checkoutSessionToken = params.checkoutSessionToken;\n    }\n    if (params.cardInfo) body.CardInfo = params.cardInfo;\n    return body as unknown as CreateTransactionBody;\n  }\n}\n","import type { HttpClient } from '../http.js';\nimport type { MetaResponse } from '../types.js';\n\n/**\n * Meta — capability introspection.\n *\n * Unauthenticated. Used by `garu doctor`, MCP tool `doctor`, and by SDK\n * consumers that want to know which payment methods and webhook events are\n * currently supported.\n */\nexport class Meta {\n  constructor(private readonly http: HttpClient) {}\n\n  /**\n   * Fetch the API's current capability payload.\n   *\n   * @example\n   * const meta = await garu.meta.get();\n   * console.log(meta.version, meta.payment_methods);\n   * if (meta.features.subscriptions) { ... }\n   */\n  async get(): Promise<MetaResponse> {\n    return this.http.call<MetaResponse>(\n      (signal) =>\n        this.http.client.GET('/api/meta', { signal }) as Promise<{\n          data?: MetaResponse;\n          error?: unknown;\n          response: Response;\n        }>\n    );\n  }\n}\n","import { createHmac, timingSafeEqual } from 'node:crypto';\n\nimport { GaruSignatureVerificationError } from './errors.js';\n\nexport interface VerifyWebhookParams {\n  /** Raw request body as received — do NOT re-serialize parsed JSON. */\n  payload: string | Buffer;\n  /** Value of the `X-Garu-Signature` header. Format: `t=<ts>,v1=<hex>`. */\n  signature: string;\n  /** The webhook endpoint's signing secret. */\n  secret: string;\n  /** Reject signatures older than this many seconds. Default: 300 (5 min). */\n  toleranceSec?: number;\n  /** Injectable for tests. Defaults to `Date.now()`. */\n  now?: () => number;\n}\n\nexport interface VerifiedWebhook {\n  /** Timestamp from the signature header, in seconds since epoch. */\n  timestamp: number;\n  /** Parsed JSON body. Throws {@link GaruSignatureVerificationError} if invalid JSON. */\n  event: unknown;\n}\n\n/**\n * Webhook helpers.\n *\n * Garu signs outgoing webhooks with HMAC-SHA256 over `${timestamp}.${payload}`\n * and delivers the signature in the `X-Garu-Signature` header as `t=<ts>,v1=<hex>`.\n * This matches the format in the backend's `webhook-delivery.service.ts`.\n *\n * @example\n * // Express example\n * app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res) => {\n *   try {\n *     const { event } = Garu.webhooks.verify({\n *       payload: req.body,\n *       signature: req.header('x-garu-signature') ?? '',\n *       secret: process.env.GARU_WEBHOOK_SECRET!\n *     });\n *     // handle event\n *     res.sendStatus(200);\n *   } catch (err) {\n *     res.sendStatus(400);\n *   }\n * });\n */\nexport const webhooks = {\n  verify(params: VerifyWebhookParams): VerifiedWebhook {\n    const { signature, secret, payload } = params;\n    const toleranceSec = params.toleranceSec ?? 300;\n    const now = params.now ?? Date.now;\n\n    if (!signature || typeof signature !== 'string') {\n      throw new GaruSignatureVerificationError('Missing or malformed X-Garu-Signature header');\n    }\n\n    const parts = parseSignatureHeader(signature);\n    if (parts === null) {\n      throw new GaruSignatureVerificationError(\n        'X-Garu-Signature header does not match expected format t=<ts>,v1=<hex>'\n      );\n    }\n\n    const payloadStr = typeof payload === 'string' ? payload : payload.toString('utf8');\n    const signedPayload = `${parts.timestamp}.${payloadStr}`;\n    const expected = createHmac('sha256', secret).update(signedPayload).digest('hex');\n\n    const expectedBuf = Buffer.from(expected, 'hex');\n    const providedBuf = Buffer.from(parts.v1, 'hex');\n    if (expectedBuf.length !== providedBuf.length || !timingSafeEqual(expectedBuf, providedBuf)) {\n      throw new GaruSignatureVerificationError('Signature does not match computed HMAC');\n    }\n\n    const nowSec = Math.floor(now() / 1000);\n    if (Math.abs(nowSec - parts.timestamp) > toleranceSec) {\n      throw new GaruSignatureVerificationError(\n        `Signature timestamp outside tolerance window (${toleranceSec}s)`\n      );\n    }\n\n    let event: unknown;\n    try {\n      event = JSON.parse(payloadStr);\n    } catch {\n      throw new GaruSignatureVerificationError('Webhook payload is not valid JSON');\n    }\n\n    return { timestamp: parts.timestamp, event };\n  }\n};\n\nfunction parseSignatureHeader(header: string): { timestamp: number; v1: string } | null {\n  const fields: Record<string, string> = {};\n  for (const part of header.split(',')) {\n    const idx = part.indexOf('=');\n    if (idx === -1) return null;\n    const key = part.slice(0, idx).trim();\n    const value = part.slice(idx + 1).trim();\n    if (!key || !value) return null;\n    fields[key] = value;\n  }\n  const t = fields.t;\n  const v1 = fields.v1;\n  if (!t || !v1) return null;\n  const timestamp = Number(t);\n  if (!Number.isFinite(timestamp) || !/^[a-f0-9]+$/i.test(v1)) return null;\n  return { timestamp, v1 };\n}\n","import { HttpClient } from './http.js';\nimport { Charges } from './resources/charges.js';\nimport { Meta } from './resources/meta.js';\nimport { webhooks } from './webhooks.js';\n\nexport interface GaruOptions {\n  /**\n   * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.\n   * Optional — public endpoints (`meta.get`, public charge creation) work without one.\n   */\n  apiKey?: string;\n  /** Override the API base URL. Default: `https://garu.com.br/api`. */\n  baseUrl?: string;\n  /** Per-request timeout in ms. Default: 30000. */\n  timeoutMs?: number;\n  /** Max retries on retryable errors (connection, 408, 429, 5xx). Default: 2. */\n  maxRetries?: number;\n  /** Injectable for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n}\n\nconst DEFAULT_BASE_URL = 'https://garu.com.br';\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst DEFAULT_MAX_RETRIES = 2;\nconst SDK_VERSION = '0.1.0';\n\n/**\n * The Garu SDK client.\n *\n * @example\n * import { Garu } from '@garuhq/node';\n *\n * const garu = new Garu({ apiKey: process.env.GARU_API_KEY });\n *\n * const charge = await garu.charges.create({\n *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',\n *   paymentMethod: 'pix',\n *   customer: {\n *     name: 'Maria Silva',\n *     email: 'maria@exemplo.com.br',\n *     document: '12345678909',\n *     phone: '11987654321'\n *   }\n * });\n */\nexport class Garu {\n  public readonly charges: Charges;\n  public readonly meta: Meta;\n\n  /**\n   * Webhook helpers. Available both as an instance member and as a static —\n   * `Garu.webhooks.verify(...)` works without constructing a client.\n   */\n  public static readonly webhooks = webhooks;\n  public readonly webhooks = webhooks;\n\n  constructor(options: GaruOptions = {}) {\n    const http = new HttpClient({\n      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,\n      apiKey: options.apiKey,\n      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,\n      userAgent: `garu-node/${SDK_VERSION}`,\n      fetch: options.fetch\n    });\n    this.charges = new Charges(http);\n    this.meta = new Meta(http);\n  }\n}\n"]}

package/dist/index.d.cts

@@ -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 };