@garuhq/node 2.0.0 → 4.0.0

package/dist/index.d.cts

@@ -390,7 +390,13 @@ interface ScheduledChargeRecord {
     /** YYYY-MM-DD in São Paulo time. */
     dueDate: string;
     methods: ScheduledPaymentMethod[];
+    recurrence: RecurrenceConfig | null;
     status: ScheduledChargeStatus;
+    subscriptionId: number | null;
+    /** ISO-8601. Set only when the series was created with `trialDays`. */
+    trialEndsAt: string | null;
+    /** Recurring only. Toggle with `setCancelAtPeriodEnd`. */
+    cancelAtPeriodEnd: boolean;
     externalReference: string | null;
     /**
      * Max days past `dueDate` the daily recovery sweep will still auto-bill a
@@ -425,7 +431,7 @@ interface ScheduledChargeEvent {
 }
 interface ScheduledChargeLinkedTransaction {
     id: number;
-    /** Centavos (BRL × 100), matching `garu.charges.*` value semantics. */
+    /** Decimal BRL (e.g. `297.50`), never centavos. */
     value: number;
     paymentMethod: string;
     status: string;
@@ -438,7 +444,14 @@ interface ScheduledChargeDetail {
     events: ScheduledChargeEvent[];
     transactions: ScheduledChargeLinkedTransaction[];
 }
-type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
+interface ScheduledChargeList {
+    data: ScheduledChargeRecord[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 /** Source of a billing attempt — see SPEC §3.1. */
 type ScheduledChargeAttemptSource = 'cycle1_interactive' | 'silent_charge' | 'card_retry' | 'manual_mark_paid' | 'fallback_pix';
 type ScheduledChargeAttemptStatus = 'pending' | 'succeeded' | 'declined' | 'canceled' | 'errored';
@@ -460,7 +473,14 @@ interface ScheduledChargeAttempt {
     gatewayChargeId: number | null;
     transactionId: number | null;
 }
-type ScheduledChargeAttemptList = PaginatedList<ScheduledChargeAttempt>;
+interface ScheduledChargeAttemptList {
+    data: ScheduledChargeAttempt[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListScheduledChargeAttemptsParams {
     page?: number;
     limit?: number;
@@ -770,9 +790,14 @@ interface WebhookEventEndpoint {
     events: string[];
     [key: string]: unknown;
 }
+/**
+ * Public API v1 webhook-event representation. Keyed on `uuid` — there is no
+ * numeric id in this shape. `webhookEndpoint.id` stays numeric: endpoint
+ * *configuration* (create/update/delete) is still dashboard-only and did
+ * not move to `/api/v1`.
+ */
 interface WebhookEvent {
-    id: number;
-    endpointId: number;
+    uuid: string;
     /** Eager-loaded endpoint snapshot. */
     webhookEndpoint: WebhookEventEndpoint;
     /** Garu event type, e.g. `transaction.payment.paid`. */
@@ -791,17 +816,24 @@ interface WebhookEvent {
     /** Response body from the most recent attempt, truncated by the gateway. */
     responseBody: string | null;
     /**
-     * When this row is a clone produced by `webhookEvents.resend(id)`, this is
-     * the numeric id of the original event the clone was forked from. `null`
-     * on every originally-fired event (and on events resurrected via the
-     * legacy `webhookEvents.retry(id)` mutation, which mutates in place
-     * instead of cloning).
+     * When this row is a clone produced by `webhookEvents.resend(uuid)`, this
+     * is the uuid of the original event the clone was forked from. `null` on
+     * every originally-fired event (and on events resurrected via the legacy
+     * `webhookEvents.retry(uuid)` mutation, which mutates in place instead of
+     * cloning).
      */
-    manualResendOf: number | null;
+    manualResendOf: string | null;
     createdAt: string;
     [key: string]: unknown;
 }
-type WebhookEventList = PaginatedList<WebhookEvent>;
+interface WebhookEventList {
+    data: WebhookEvent[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListWebhookEventsParams {
     page?: number;
     limit?: number;
@@ -1561,9 +1593,13 @@ declare class ScheduledCharges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a new scheduled charge. Auto-attaches `X-Idempotency-Key`
-     * (UUIDv4 if you don't pass `idempotencyKey`) so retries on transient
-     * network failures don't silently double-create.
+     * Create a new scheduled charge. The SDK attaches an `X-Idempotency-Key`
+     * header (UUIDv4 unless you pass `idempotencyKey`), but the gateway does
+     * not currently deduplicate `/scheduled-charges` creates against it — a
+     * retry after a network failure can create more than one series. Pair
+     * this with your own retry-suppression (e.g. check `list` for an existing
+     * series with the same `externalReference`) if that matters for your
+     * integration.
      *
      * @example
      * const charge = await garu.scheduledCharges.create({
@@ -1680,17 +1716,15 @@ declare class ScheduledCharges {
      * const result = await garu.scheduledCharges.chargeNow('sch_abc123');
      * switch (result.outcome) {
      *   case 'dispatched':
-     *     console.log(`Cobrança enviada (ciclo ${result.cycleNumber}).`);
+     *     result.cycleNumber; // billed this cycle
      *     break;
      *   case 'already_sent':
-     *     console.log('Já havia sido enviada — nada a fazer.');
-     *     break;
+     *     break; // nothing to do
      *   case 'failed':
-     *     // result.reason is e.g. 'card_expired' or a gateway decline code
-     *     console.error(`Falha na cobrança: ${result.reason}. ${result.message}`);
+     *     result.reason; // e.g. 'card_expired' or a gateway decline code
      *     break;
      *   case 'not_sent':
-     *     console.warn(`Não enviada (${result.reason}): ${result.message}`);
+     *     result.reason;
      *     break;
      * }
      */
@@ -1754,7 +1788,8 @@ declare class ScheduledCharges {
 /**
  * Webhook events — the seller-facing delivery log for outbound webhooks.
  *
- * Every time the gateway fires a webhook (e.g. `transaction.payment.paid`,
+ * Backed by `/api/v1/webhook-events`, keyed on `uuid`. Every time the
+ * gateway fires a webhook (e.g. `transaction.payment.paid`,
  * `scheduled_charge.cycle_failed`), it persists one row per destination
  * endpoint with the full payload, the HTTP outcome, and the retry schedule.
  * Use this resource to audit deliveries from the seller's API key — the
@@ -1762,6 +1797,7 @@ declare class ScheduledCharges {
  *
  * Webhook endpoint *configuration* (URL, subscribed events, secret) is still
  * dashboard-only — this resource only covers the event log + manual retries.
+ * `webhookEndpoint.id` on every event stays a numeric id for that reason.
  */
 declare class WebhookEvents {
     private readonly http;
@@ -1784,16 +1820,14 @@ declare class WebhookEvents {
      */
     list(params?: ListWebhookEventsParams): Promise<WebhookEventList>;
     /**
-     * Fetch one webhook event by numeric ID — includes the full payload, the
+     * Fetch one webhook event by uuid — includes the full payload, the
      * embedded endpoint snapshot, and the most recent response status/body.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * if (event.status === 'failed') {
-     *   console.log(event.responseStatus, event.responseBody);
-     * }
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * event.status === 'failed' && event.responseStatus;
      */
-    get(id: number): Promise<WebhookEvent>;
+    get(uuid: string): Promise<WebhookEvent>;
     /**
      * @deprecated For most cases prefer {@link resend}, which preserves the
      * original event's audit trail by cloning rather than mutating. `retry()`
@@ -1802,21 +1836,21 @@ declare class WebhookEvents {
      * explicitly want the legacy in-place semantics (and for backwards
      * compatibility with older CLI / MCP releases).
      *
-     * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+     * Re-deliver a webhook event by uuid. Resets it to `pending`, clears the
      * retry schedule, and triggers an immediate delivery attempt. Works on
      * any status (`success`, `failed`, `pending`).
      *
      * @example
      * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
      * for (const event of failed.data) {
-     *   await garu.webhookEvents.retry(event.id);
+     *   await garu.webhookEvents.retry(event.uuid);
      * }
      */
-    retry(id: number): Promise<WebhookEvent>;
+    retry(uuid: string): Promise<WebhookEvent>;
     /**
-     * Re-deliver a webhook event by ID, audit-trail preserving. Unlike
+     * Re-deliver a webhook event by uuid, audit-trail preserving. Unlike
      * {@link retry}, this does *not* mutate the original row — it inserts a
-     * fresh event (new numeric id) that points back at the source via
+     * fresh event (new uuid) that points back at the source via
      * `manualResendOf`, then dispatches that clone. The original row is
      * untouched, so the historical record of the prior failure (and its
      * response status / body) is preserved.
@@ -1827,27 +1861,27 @@ declare class WebhookEvents {
      * delivery's outcome to remain on the record.
      *
      * **Outbound delivery semantics**: the gateway POSTs the clone with
-     * `Idempotency-Key: resend_<originalId>` (where `<originalId>` is the id
-     * of the source event, not the clone). Recipient handlers that key off
+     * `Idempotency-Key: resend_<cloneUuid>`. Recipient handlers that key off
      * `Idempotency-Key` will see this as a distinct delivery from the
      * original — distinguishable both by the `resend_` prefix and by reading
      * the response payload's `manualResendOf` field.
      *
-     * **SDK→gateway dedup**: the SDK auto-attaches `X-Idempotency-Key`
-     * (UUIDv4 unless you pass `idempotencyKey`) so transient transport
-     * retries (5xx → SDK backoff) cannot create duplicate clones — the
-     * backend returns the original clone on the second call within 24h.
+     * The SDK also attaches an `X-Idempotency-Key` header (UUIDv4 unless you
+     * pass `idempotencyKey`); the gateway does not currently deduplicate
+     * `/resend` calls against it, so retrying this call from your own code
+     * after a network failure can create more than one clone — pair it with
+     * your own retry-suppression if that matters for your integration.
      *
-     * Returns the *clone* event (new id), not the original. The original is
+     * Returns the *clone* event (new uuid), not the original. The original is
      * unchanged on the server.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * const clone = await garu.webhookEvents.resend(42);
-     * clone.id !== event.id;            // true — clone has its own id
-     * clone.manualResendOf === event.id; // true — points back at the source
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * const clone = await garu.webhookEvents.resend(event.uuid);
+     * clone.uuid !== event.uuid;            // true — clone has its own uuid
+     * clone.manualResendOf === event.uuid; // true — points back at the source
      */
-    resend(id: number, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
+    resend(uuid: string, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
 }
 
 interface GaruOptions {

package/dist/index.d.ts

@@ -390,7 +390,13 @@ interface ScheduledChargeRecord {
     /** YYYY-MM-DD in São Paulo time. */
     dueDate: string;
     methods: ScheduledPaymentMethod[];
+    recurrence: RecurrenceConfig | null;
     status: ScheduledChargeStatus;
+    subscriptionId: number | null;
+    /** ISO-8601. Set only when the series was created with `trialDays`. */
+    trialEndsAt: string | null;
+    /** Recurring only. Toggle with `setCancelAtPeriodEnd`. */
+    cancelAtPeriodEnd: boolean;
     externalReference: string | null;
     /**
      * Max days past `dueDate` the daily recovery sweep will still auto-bill a
@@ -425,7 +431,7 @@ interface ScheduledChargeEvent {
 }
 interface ScheduledChargeLinkedTransaction {
     id: number;
-    /** Centavos (BRL × 100), matching `garu.charges.*` value semantics. */
+    /** Decimal BRL (e.g. `297.50`), never centavos. */
     value: number;
     paymentMethod: string;
     status: string;
@@ -438,7 +444,14 @@ interface ScheduledChargeDetail {
     events: ScheduledChargeEvent[];
     transactions: ScheduledChargeLinkedTransaction[];
 }
-type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
+interface ScheduledChargeList {
+    data: ScheduledChargeRecord[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 /** Source of a billing attempt — see SPEC §3.1. */
 type ScheduledChargeAttemptSource = 'cycle1_interactive' | 'silent_charge' | 'card_retry' | 'manual_mark_paid' | 'fallback_pix';
 type ScheduledChargeAttemptStatus = 'pending' | 'succeeded' | 'declined' | 'canceled' | 'errored';
@@ -460,7 +473,14 @@ interface ScheduledChargeAttempt {
     gatewayChargeId: number | null;
     transactionId: number | null;
 }
-type ScheduledChargeAttemptList = PaginatedList<ScheduledChargeAttempt>;
+interface ScheduledChargeAttemptList {
+    data: ScheduledChargeAttempt[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListScheduledChargeAttemptsParams {
     page?: number;
     limit?: number;
@@ -770,9 +790,14 @@ interface WebhookEventEndpoint {
     events: string[];
     [key: string]: unknown;
 }
+/**
+ * Public API v1 webhook-event representation. Keyed on `uuid` — there is no
+ * numeric id in this shape. `webhookEndpoint.id` stays numeric: endpoint
+ * *configuration* (create/update/delete) is still dashboard-only and did
+ * not move to `/api/v1`.
+ */
 interface WebhookEvent {
-    id: number;
-    endpointId: number;
+    uuid: string;
     /** Eager-loaded endpoint snapshot. */
     webhookEndpoint: WebhookEventEndpoint;
     /** Garu event type, e.g. `transaction.payment.paid`. */
@@ -791,17 +816,24 @@ interface WebhookEvent {
     /** Response body from the most recent attempt, truncated by the gateway. */
     responseBody: string | null;
     /**
-     * When this row is a clone produced by `webhookEvents.resend(id)`, this is
-     * the numeric id of the original event the clone was forked from. `null`
-     * on every originally-fired event (and on events resurrected via the
-     * legacy `webhookEvents.retry(id)` mutation, which mutates in place
-     * instead of cloning).
+     * When this row is a clone produced by `webhookEvents.resend(uuid)`, this
+     * is the uuid of the original event the clone was forked from. `null` on
+     * every originally-fired event (and on events resurrected via the legacy
+     * `webhookEvents.retry(uuid)` mutation, which mutates in place instead of
+     * cloning).
      */
-    manualResendOf: number | null;
+    manualResendOf: string | null;
     createdAt: string;
     [key: string]: unknown;
 }
-type WebhookEventList = PaginatedList<WebhookEvent>;
+interface WebhookEventList {
+    data: WebhookEvent[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListWebhookEventsParams {
     page?: number;
     limit?: number;
@@ -1561,9 +1593,13 @@ declare class ScheduledCharges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a new scheduled charge. Auto-attaches `X-Idempotency-Key`
-     * (UUIDv4 if you don't pass `idempotencyKey`) so retries on transient
-     * network failures don't silently double-create.
+     * Create a new scheduled charge. The SDK attaches an `X-Idempotency-Key`
+     * header (UUIDv4 unless you pass `idempotencyKey`), but the gateway does
+     * not currently deduplicate `/scheduled-charges` creates against it — a
+     * retry after a network failure can create more than one series. Pair
+     * this with your own retry-suppression (e.g. check `list` for an existing
+     * series with the same `externalReference`) if that matters for your
+     * integration.
      *
      * @example
      * const charge = await garu.scheduledCharges.create({
@@ -1680,17 +1716,15 @@ declare class ScheduledCharges {
      * const result = await garu.scheduledCharges.chargeNow('sch_abc123');
      * switch (result.outcome) {
      *   case 'dispatched':
-     *     console.log(`Cobrança enviada (ciclo ${result.cycleNumber}).`);
+     *     result.cycleNumber; // billed this cycle
      *     break;
      *   case 'already_sent':
-     *     console.log('Já havia sido enviada — nada a fazer.');
-     *     break;
+     *     break; // nothing to do
      *   case 'failed':
-     *     // result.reason is e.g. 'card_expired' or a gateway decline code
-     *     console.error(`Falha na cobrança: ${result.reason}. ${result.message}`);
+     *     result.reason; // e.g. 'card_expired' or a gateway decline code
      *     break;
      *   case 'not_sent':
-     *     console.warn(`Não enviada (${result.reason}): ${result.message}`);
+     *     result.reason;
      *     break;
      * }
      */
@@ -1754,7 +1788,8 @@ declare class ScheduledCharges {
 /**
  * Webhook events — the seller-facing delivery log for outbound webhooks.
  *
- * Every time the gateway fires a webhook (e.g. `transaction.payment.paid`,
+ * Backed by `/api/v1/webhook-events`, keyed on `uuid`. Every time the
+ * gateway fires a webhook (e.g. `transaction.payment.paid`,
  * `scheduled_charge.cycle_failed`), it persists one row per destination
  * endpoint with the full payload, the HTTP outcome, and the retry schedule.
  * Use this resource to audit deliveries from the seller's API key — the
@@ -1762,6 +1797,7 @@ declare class ScheduledCharges {
  *
  * Webhook endpoint *configuration* (URL, subscribed events, secret) is still
  * dashboard-only — this resource only covers the event log + manual retries.
+ * `webhookEndpoint.id` on every event stays a numeric id for that reason.
  */
 declare class WebhookEvents {
     private readonly http;
@@ -1784,16 +1820,14 @@ declare class WebhookEvents {
      */
     list(params?: ListWebhookEventsParams): Promise<WebhookEventList>;
     /**
-     * Fetch one webhook event by numeric ID — includes the full payload, the
+     * Fetch one webhook event by uuid — includes the full payload, the
      * embedded endpoint snapshot, and the most recent response status/body.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * if (event.status === 'failed') {
-     *   console.log(event.responseStatus, event.responseBody);
-     * }
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * event.status === 'failed' && event.responseStatus;
      */
-    get(id: number): Promise<WebhookEvent>;
+    get(uuid: string): Promise<WebhookEvent>;
     /**
      * @deprecated For most cases prefer {@link resend}, which preserves the
      * original event's audit trail by cloning rather than mutating. `retry()`
@@ -1802,21 +1836,21 @@ declare class WebhookEvents {
      * explicitly want the legacy in-place semantics (and for backwards
      * compatibility with older CLI / MCP releases).
      *
-     * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+     * Re-deliver a webhook event by uuid. Resets it to `pending`, clears the
      * retry schedule, and triggers an immediate delivery attempt. Works on
      * any status (`success`, `failed`, `pending`).
      *
      * @example
      * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
      * for (const event of failed.data) {
-     *   await garu.webhookEvents.retry(event.id);
+     *   await garu.webhookEvents.retry(event.uuid);
      * }
      */
-    retry(id: number): Promise<WebhookEvent>;
+    retry(uuid: string): Promise<WebhookEvent>;
     /**
-     * Re-deliver a webhook event by ID, audit-trail preserving. Unlike
+     * Re-deliver a webhook event by uuid, audit-trail preserving. Unlike
      * {@link retry}, this does *not* mutate the original row — it inserts a
-     * fresh event (new numeric id) that points back at the source via
+     * fresh event (new uuid) that points back at the source via
      * `manualResendOf`, then dispatches that clone. The original row is
      * untouched, so the historical record of the prior failure (and its
      * response status / body) is preserved.
@@ -1827,27 +1861,27 @@ declare class WebhookEvents {
      * delivery's outcome to remain on the record.
      *
      * **Outbound delivery semantics**: the gateway POSTs the clone with
-     * `Idempotency-Key: resend_<originalId>` (where `<originalId>` is the id
-     * of the source event, not the clone). Recipient handlers that key off
+     * `Idempotency-Key: resend_<cloneUuid>`. Recipient handlers that key off
      * `Idempotency-Key` will see this as a distinct delivery from the
      * original — distinguishable both by the `resend_` prefix and by reading
      * the response payload's `manualResendOf` field.
      *
-     * **SDK→gateway dedup**: the SDK auto-attaches `X-Idempotency-Key`
-     * (UUIDv4 unless you pass `idempotencyKey`) so transient transport
-     * retries (5xx → SDK backoff) cannot create duplicate clones — the
-     * backend returns the original clone on the second call within 24h.
+     * The SDK also attaches an `X-Idempotency-Key` header (UUIDv4 unless you
+     * pass `idempotencyKey`); the gateway does not currently deduplicate
+     * `/resend` calls against it, so retrying this call from your own code
+     * after a network failure can create more than one clone — pair it with
+     * your own retry-suppression if that matters for your integration.
      *
-     * Returns the *clone* event (new id), not the original. The original is
+     * Returns the *clone* event (new uuid), not the original. The original is
      * unchanged on the server.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * const clone = await garu.webhookEvents.resend(42);
-     * clone.id !== event.id;            // true — clone has its own id
-     * clone.manualResendOf === event.id; // true — points back at the source
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * const clone = await garu.webhookEvents.resend(event.uuid);
+     * clone.uuid !== event.uuid;            // true — clone has its own uuid
+     * clone.manualResendOf === event.uuid; // true — points back at the source
      */
-    resend(id: number, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
+    resend(uuid: string, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
 }
 
 interface GaruOptions {