@garuhq/node 0.1.0

package/dist/index.js

@@ -0,0 +1,428 @@
+import createClient from 'openapi-fetch';
+import { createHmac, timingSafeEqual, randomUUID } from 'crypto';
+
+// src/http.ts
+
+// src/errors.ts
+var GaruError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "GaruError";
+    this.code = code;
+  }
+};
+var GaruConnectionError = class extends GaruError {
+  connectionCause;
+  constructor(message, connectionCause) {
+    super("connection_error", message);
+    this.name = "GaruConnectionError";
+    this.connectionCause = connectionCause;
+  }
+};
+var GaruSignatureVerificationError = class extends GaruError {
+  constructor(message) {
+    super("signature_verification_failed", message);
+    this.name = "GaruSignatureVerificationError";
+  }
+};
+var GaruAPIError = class extends GaruError {
+  status;
+  requestId;
+  body;
+  constructor(code, message, status, requestId, body) {
+    super(code, message);
+    this.name = "GaruAPIError";
+    this.status = status;
+    this.requestId = requestId;
+    this.body = body;
+  }
+};
+var GaruAuthenticationError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("authentication_error", message, status, requestId, body);
+    this.name = "GaruAuthenticationError";
+  }
+};
+var GaruPermissionError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("permission_error", message, status, requestId, body);
+    this.name = "GaruPermissionError";
+  }
+};
+var GaruNotFoundError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("not_found", message, status, requestId, body);
+    this.name = "GaruNotFoundError";
+  }
+};
+var GaruValidationError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("validation_error", message, status, requestId, body);
+    this.name = "GaruValidationError";
+  }
+};
+var GaruRateLimitError = class extends GaruAPIError {
+  retryAfterSec;
+  constructor(message, status, requestId, body, retryAfterSec) {
+    super("rate_limited", message, status, requestId, body);
+    this.name = "GaruRateLimitError";
+    this.retryAfterSec = retryAfterSec;
+  }
+};
+var GaruServerError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("server_error", message, status, requestId, body);
+    this.name = "GaruServerError";
+  }
+};
+function mapApiError(status, body, requestId, retryAfterSec) {
+  const message = extractMessage(body) ?? `Garu API returned HTTP ${status}`;
+  if (status === 401)
+    return new GaruAuthenticationError(message, status, requestId, body);
+  if (status === 403)
+    return new GaruPermissionError(message, status, requestId, body);
+  if (status === 404)
+    return new GaruNotFoundError(message, status, requestId, body);
+  if (status === 400 || status === 422) {
+    return new GaruValidationError(message, status, requestId, body);
+  }
+  if (status === 429) {
+    return new GaruRateLimitError(message, status, requestId, body, retryAfterSec);
+  }
+  if (status >= 500)
+    return new GaruServerError(message, status, requestId, body);
+  return new GaruAPIError("api_error", message, status, requestId, body);
+}
+function extractMessage(body) {
+  if (typeof body === "string")
+    return body;
+  if (body && typeof body === "object") {
+    const m = body.message;
+    if (typeof m === "string")
+      return m;
+    if (Array.isArray(m) && m.every((x) => typeof x === "string"))
+      return m.join("; ");
+  }
+  return null;
+}
+
+// src/http.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var HttpClient = class {
+  client;
+  cfg;
+  constructor(cfg) {
+    this.cfg = cfg;
+    const fetchImpl = cfg.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new GaruConnectionError(
+        "No fetch implementation available. Node.js >= 18 is required."
+      );
+    }
+    const headers = {
+      Accept: "application/json",
+      "User-Agent": cfg.userAgent
+    };
+    if (cfg.apiKey)
+      headers.Authorization = `Bearer ${cfg.apiKey}`;
+    this.client = createClient({
+      baseUrl: cfg.baseUrl.replace(/\/+$/, ""),
+      fetch: fetchImpl,
+      headers
+    });
+  }
+  /**
+   * 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`.
+   */
+  async call(fn) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.cfg.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.cfg.timeoutMs);
+      try {
+        const { data, error, response } = await fn(controller.signal);
+        clearTimeout(timer);
+        if (response.ok) {
+          return data;
+        }
+        const requestId = response.headers.get("x-request-id");
+        const retryAfterSec = parseRetryAfter(response.headers.get("retry-after"));
+        const apiError = mapApiError(response.status, error ?? null, requestId, retryAfterSec);
+        lastError = apiError;
+        if (!RETRYABLE_STATUSES.has(response.status) || attempt === this.cfg.maxRetries) {
+          throw apiError;
+        }
+        await sleep(backoffDelay(attempt, retryAfterSec));
+        continue;
+      } catch (err) {
+        clearTimeout(timer);
+        if (isGaruApiError(err))
+          throw err;
+        const connErr = err instanceof Error && err.name === "AbortError" ? new GaruConnectionError(`Request timed out after ${this.cfg.timeoutMs}ms`, err) : new GaruConnectionError(err instanceof Error ? err.message : "Network error", err);
+        lastError = connErr;
+        if (attempt === this.cfg.maxRetries)
+          throw connErr;
+        await sleep(backoffDelay(attempt, null));
+        continue;
+      }
+    }
+    throw lastError ?? new GaruConnectionError("Request failed with no error captured");
+  }
+};
+function isGaruApiError(err) {
+  return err instanceof Error && err.name.startsWith("Garu") && err.name.endsWith("Error");
+}
+function parseRetryAfter(value) {
+  if (!value)
+    return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+function backoffDelay(attempt, retryAfterSec) {
+  if (retryAfterSec !== null) {
+    return retryAfterSec * 1e3 + Math.random() * 250;
+  }
+  const base = 500 * 2 ** attempt;
+  const cap = 8e3;
+  return Math.min(cap, base) * Math.random();
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function generateIdempotencyKey() {
+  return randomUUID();
+}
+
+// src/types.ts
+function toWirePaymentMethod(pm) {
+  return pm === "credit_card" ? "creditcard" : pm;
+}
+
+// src/resources/charges.ts
+var Charges = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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
+   *   }
+   * });
+   */
+  async create(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const body = this.buildCreateBody(params);
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/transactions", {
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
+        signal
+      })
+    );
+  }
+  /**
+   * Fetch a single charge by numeric ID.
+   *
+   * @example
+   * const charge = await garu.charges.get(4472);
+   * if (charge.status === 'paid') { ... }
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET("/api/transactions/{id}", {
+        params: { path: { id } },
+        signal
+      })
+    );
+  }
+  /**
+   * 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' });
+   */
+  async refund(id, params = {}) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const body = {};
+    if (params.amount !== void 0)
+      body.amount = params.amount;
+    if (params.reason !== void 0)
+      body.reason = params.reason;
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/transactions/{id}/refund", {
+        params: { path: { id } },
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
+        signal
+      })
+    );
+  }
+  buildCreateBody(params) {
+    const body = {
+      customer: params.customer,
+      productId: params.productId,
+      paymentMethodId: toWirePaymentMethod(params.paymentMethod),
+      link: params.link ?? null,
+      affiliateId: params.affiliateId ?? null
+    };
+    if (params.additionalInfo !== void 0)
+      body.additionalInfo = params.additionalInfo;
+    if (params.priceId !== void 0)
+      body.priceId = params.priceId;
+    if (params.checkoutSessionToken !== void 0) {
+      body.checkoutSessionToken = params.checkoutSessionToken;
+    }
+    if (params.cardInfo)
+      body.CardInfo = params.cardInfo;
+    return body;
+  }
+};
+
+// src/resources/meta.ts
+var Meta = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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) { ... }
+   */
+  async get() {
+    return this.http.call(
+      (signal) => this.http.client.GET("/api/meta", { signal })
+    );
+  }
+};
+var webhooks = {
+  verify(params) {
+    const { signature, secret, payload } = params;
+    const toleranceSec = params.toleranceSec ?? 300;
+    const now = params.now ?? Date.now;
+    if (!signature || typeof signature !== "string") {
+      throw new GaruSignatureVerificationError("Missing or malformed X-Garu-Signature header");
+    }
+    const parts = parseSignatureHeader(signature);
+    if (parts === null) {
+      throw new GaruSignatureVerificationError(
+        "X-Garu-Signature header does not match expected format t=<ts>,v1=<hex>"
+      );
+    }
+    const payloadStr = typeof payload === "string" ? payload : payload.toString("utf8");
+    const signedPayload = `${parts.timestamp}.${payloadStr}`;
+    const expected = createHmac("sha256", secret).update(signedPayload).digest("hex");
+    const expectedBuf = Buffer.from(expected, "hex");
+    const providedBuf = Buffer.from(parts.v1, "hex");
+    if (expectedBuf.length !== providedBuf.length || !timingSafeEqual(expectedBuf, providedBuf)) {
+      throw new GaruSignatureVerificationError("Signature does not match computed HMAC");
+    }
+    const nowSec = Math.floor(now() / 1e3);
+    if (Math.abs(nowSec - parts.timestamp) > toleranceSec) {
+      throw new GaruSignatureVerificationError(
+        `Signature timestamp outside tolerance window (${toleranceSec}s)`
+      );
+    }
+    let event;
+    try {
+      event = JSON.parse(payloadStr);
+    } catch {
+      throw new GaruSignatureVerificationError("Webhook payload is not valid JSON");
+    }
+    return { timestamp: parts.timestamp, event };
+  }
+};
+function parseSignatureHeader(header) {
+  const fields = {};
+  for (const part of header.split(",")) {
+    const idx = part.indexOf("=");
+    if (idx === -1)
+      return null;
+    const key = part.slice(0, idx).trim();
+    const value = part.slice(idx + 1).trim();
+    if (!key || !value)
+      return null;
+    fields[key] = value;
+  }
+  const t = fields.t;
+  const v1 = fields.v1;
+  if (!t || !v1)
+    return null;
+  const timestamp = Number(t);
+  if (!Number.isFinite(timestamp) || !/^[a-f0-9]+$/i.test(v1))
+    return null;
+  return { timestamp, v1 };
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://garu.com.br";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var SDK_VERSION = "0.1.0";
+var Garu = class {
+  charges;
+  meta;
+  /**
+   * Webhook helpers. Available both as an instance member and as a static —
+   * `Garu.webhooks.verify(...)` works without constructing a client.
+   */
+  static webhooks = webhooks;
+  webhooks = webhooks;
+  constructor(options = {}) {
+    const http = new HttpClient({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      apiKey: options.apiKey,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      userAgent: `garu-node/${SDK_VERSION}`,
+      fetch: options.fetch
+    });
+    this.charges = new Charges(http);
+    this.meta = new Meta(http);
+  }
+};
+
+export { Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, GaruNotFoundError, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, webhooks };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.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/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@garuhq/node",
+  "version": "0.1.0",
+  "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
+  "license": "MIT",
+  "homepage": "https://garu.com.br",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Garu-Pagamentos/garu-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Garu-Pagamentos/garu-node/issues"
+  },
+  "keywords": [
+    "garu",
+    "payments",
+    "pix",
+    "boleto",
+    "credit-card",
+    "brazil",
+    "fintech",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "generate": "curl -sf https://garu.com.br/api/swagger-json -o src/generated/openapi.json && openapi-typescript src/generated/openapi.json -o src/generated/schema.d.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "20.12.7",
+    "openapi-typescript": "7.4.2",
+    "tsup": "8.0.2",
+    "typescript": "5.4.5",
+    "vitest": "1.5.0"
+  },
+  "dependencies": {
+    "openapi-fetch": "0.9.7"
+  }
+}