@garuhq/node 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -464,11 +464,80 @@ var Meta = class {
 };
 
 // src/resources/products.ts
+var ProductPortalConfigResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Get the portal customization for a product. Returns `null` when no
+   * per-product config exists (the product falls back to seller-level
+   * portal config).
+   *
+   * @example
+   * const cfg = await garu.products.portalConfig.get(57);
+   */
+  async get(productId) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Create or merge the portal customization (idempotent upsert). Both
+   * `set` and `patch` have the same merge semantics — only fields present
+   * in the body are written, unspecified fields keep their persisted
+   * value. Use `clear` to reset everything.
+   *
+   * @example
+   * await garu.products.portalConfig.set(57, {
+   *   businessName: 'Coach Maria — Corrida & Trilha',
+   *   primaryColor: '#257264',
+   *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+   * });
+   */
+  async set(productId, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/products/${productId}/portal-config`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
+  async patch(productId, params) {
+    return this.http.call(
+      (signal) => this.http.client.PATCH(`/api/products/${productId}/portal-config`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Remove the per-product config. The product falls back to the
+   * seller-level portal config. Returns `{ removed: true }` when a row was
+   * deleted, `{ removed: false }` when there was nothing to remove.
+   *
+   * @example
+   * await garu.products.portalConfig.clear(57);
+   */
+  async clear(productId) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+};
 var Products = class {
   constructor(http) {
     this.http = http;
+    this.portalConfig = new ProductPortalConfigResource(http);
   }
   http;
+  /** Per-product portal customization (Garu v0.8.0). */
+  portalConfig;
   /**
    * List products for the authenticated seller, with pagination and search.
    *

package/dist/index.d.cts

@@ -485,6 +485,98 @@ interface MetaResponse {
     dashboard_url: string;
     support_email: string;
 }
+/**
+ * Canonical Garu failure code on `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` events. Stable across acquirer changes —
+ * branch on this rather than the raw Celcoin code.
+ */
+type GaruFailureCode = 'insufficient_funds' | 'card_declined' | 'card_expired' | 'card_canceled' | 'processing_error' | 'issuer_unavailable' | 'fraud_suspected' | 'invalid_cvv' | 'do_not_honor_repeated' | 'unknown';
+/**
+ * Shape of the failure trio added to `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` payloads. Sellers should always receive
+ * a non-null `failureCode` — `unknown` is the sentinel when the gateway
+ * didn't surface enough detail to map.
+ */
+interface FailurePayload {
+    failureCode: GaruFailureCode;
+    failureReason: string | null;
+    /** Raw acquirer code (Celcoin's ABECS code today). For forensics only. */
+    gatewayFailureCode: string | null;
+}
+/**
+ * `payment_method.expiring_soon` — fires at 30/14/7 days before card
+ * expiry, idempotent per stage. Use to nudge the customer to update
+ * their card before silent-charge starts failing.
+ */
+interface PaymentMethodExpiringPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+    daysUntilExpiry: 30 | 14 | 7;
+}
+/**
+ * `payment_method.expired` — fires once on the day-of-expiry when the cron
+ * flips `status='expired'`. Future silent charges short-circuit
+ * with `failureCode='card_expired'` instead of hitting the acquirer.
+ */
+interface PaymentMethodExpiredPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+}
+/**
+ * Per-product portal customization (Atletia coach-as-product modeling and
+ * any other B2B2C platform). `null` fields inherit from the seller-level
+ * portal config.
+ */
+interface ProductPortalConfig {
+    id: number;
+    productId: number;
+    businessName: string | null;
+    logoUrl: string | null;
+    primaryColor: string | null;
+    allowCancelSubscription: boolean | null;
+    allowUpdatePaymentMethod: boolean | null;
+    allowUpdateBillingInfo: boolean | null;
+    allowViewInvoices: boolean | null;
+    allowApplyCoupons: boolean | null;
+    requireCancelReason: boolean | null;
+    cancelAtPeriodEndOnly: boolean | null;
+    sendCancellationEmail: boolean | null;
+    sendPaymentMethodUpdatedEmail: boolean | null;
+    customSuccessMessage: string | null;
+    customCancellationMessage: string | null;
+    customWelcomeText: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Body for `POST` / `PATCH /api/products/:id/portal-config`. Both verbs
+ * are upsert with merge semantics — only fields present are written;
+ * unspecified fields keep their persisted value. Use the `clear`
+ * method (DELETE) to reset everything.
+ */
+interface SetProductPortalConfigParams {
+    businessName?: string | null;
+    logoUrl?: string | null;
+    primaryColor?: string | null;
+    allowCancelSubscription?: boolean | null;
+    allowUpdatePaymentMethod?: boolean | null;
+    allowUpdateBillingInfo?: boolean | null;
+    allowViewInvoices?: boolean | null;
+    allowApplyCoupons?: boolean | null;
+    requireCancelReason?: boolean | null;
+    cancelAtPeriodEndOnly?: boolean | null;
+    sendCancellationEmail?: boolean | null;
+    sendPaymentMethodUpdatedEmail?: boolean | null;
+    customSuccessMessage?: string | null;
+    customCancellationMessage?: string | null;
+    customWelcomeText?: string | null;
+}
 
 /**
  * Charges — the core of the Garu API.
@@ -657,13 +749,61 @@ declare class Meta {
 }
 
 /**
- * Products — discover products available to charge.
+ * Per-product portal customization (Garu v0.8.0). Used by B2B2C platforms
+ * that model their professionals/coaches as Products under a single seller
+ * and want per-product branding on the customer payment + portal pages.
+ */
+declare class ProductPortalConfigResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the portal customization for a product. Returns `null` when no
+     * per-product config exists (the product falls back to seller-level
+     * portal config).
+     *
+     * @example
+     * const cfg = await garu.products.portalConfig.get(57);
+     */
+    get(productId: number): Promise<ProductPortalConfig | null>;
+    /**
+     * Create or merge the portal customization (idempotent upsert). Both
+     * `set` and `patch` have the same merge semantics — only fields present
+     * in the body are written, unspecified fields keep their persisted
+     * value. Use `clear` to reset everything.
+     *
+     * @example
+     * await garu.products.portalConfig.set(57, {
+     *   businessName: 'Coach Maria — Corrida & Trilha',
+     *   primaryColor: '#257264',
+     *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+     * });
+     */
+    set(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
+    patch(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    /**
+     * Remove the per-product config. The product falls back to the
+     * seller-level portal config. Returns `{ removed: true }` when a row was
+     * deleted, `{ removed: false }` when there was nothing to remove.
+     *
+     * @example
+     * await garu.products.portalConfig.clear(57);
+     */
+    clear(productId: number): Promise<{
+        removed: boolean;
+    }>;
+}
+/**
+ * Products — discover products available to charge, and customize the
+ * per-product portal experience (v0.8.0).
  *
  * Products are scoped to the seller identified by the API key. The UUID
  * returned here is the same identifier accepted by `charges.create({ productId })`.
  */
 declare class Products {
     private readonly http;
+    /** Per-product portal customization (Garu v0.8.0). */
+    readonly portalConfig: ProductPortalConfigResource;
     constructor(http: HttpClient);
     /**
      * List products for the authenticated seller, with pagination and search.
@@ -931,4 +1071,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PostponeScheduledChargeParams, type Product, type ProductList, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };

package/dist/index.d.ts

@@ -485,6 +485,98 @@ interface MetaResponse {
     dashboard_url: string;
     support_email: string;
 }
+/**
+ * Canonical Garu failure code on `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` events. Stable across acquirer changes —
+ * branch on this rather than the raw Celcoin code.
+ */
+type GaruFailureCode = 'insufficient_funds' | 'card_declined' | 'card_expired' | 'card_canceled' | 'processing_error' | 'issuer_unavailable' | 'fraud_suspected' | 'invalid_cvv' | 'do_not_honor_repeated' | 'unknown';
+/**
+ * Shape of the failure trio added to `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` payloads. Sellers should always receive
+ * a non-null `failureCode` — `unknown` is the sentinel when the gateway
+ * didn't surface enough detail to map.
+ */
+interface FailurePayload {
+    failureCode: GaruFailureCode;
+    failureReason: string | null;
+    /** Raw acquirer code (Celcoin's ABECS code today). For forensics only. */
+    gatewayFailureCode: string | null;
+}
+/**
+ * `payment_method.expiring_soon` — fires at 30/14/7 days before card
+ * expiry, idempotent per stage. Use to nudge the customer to update
+ * their card before silent-charge starts failing.
+ */
+interface PaymentMethodExpiringPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+    daysUntilExpiry: 30 | 14 | 7;
+}
+/**
+ * `payment_method.expired` — fires once on the day-of-expiry when the cron
+ * flips `status='expired'`. Future silent charges short-circuit
+ * with `failureCode='card_expired'` instead of hitting the acquirer.
+ */
+interface PaymentMethodExpiredPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+}
+/**
+ * Per-product portal customization (Atletia coach-as-product modeling and
+ * any other B2B2C platform). `null` fields inherit from the seller-level
+ * portal config.
+ */
+interface ProductPortalConfig {
+    id: number;
+    productId: number;
+    businessName: string | null;
+    logoUrl: string | null;
+    primaryColor: string | null;
+    allowCancelSubscription: boolean | null;
+    allowUpdatePaymentMethod: boolean | null;
+    allowUpdateBillingInfo: boolean | null;
+    allowViewInvoices: boolean | null;
+    allowApplyCoupons: boolean | null;
+    requireCancelReason: boolean | null;
+    cancelAtPeriodEndOnly: boolean | null;
+    sendCancellationEmail: boolean | null;
+    sendPaymentMethodUpdatedEmail: boolean | null;
+    customSuccessMessage: string | null;
+    customCancellationMessage: string | null;
+    customWelcomeText: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Body for `POST` / `PATCH /api/products/:id/portal-config`. Both verbs
+ * are upsert with merge semantics — only fields present are written;
+ * unspecified fields keep their persisted value. Use the `clear`
+ * method (DELETE) to reset everything.
+ */
+interface SetProductPortalConfigParams {
+    businessName?: string | null;
+    logoUrl?: string | null;
+    primaryColor?: string | null;
+    allowCancelSubscription?: boolean | null;
+    allowUpdatePaymentMethod?: boolean | null;
+    allowUpdateBillingInfo?: boolean | null;
+    allowViewInvoices?: boolean | null;
+    allowApplyCoupons?: boolean | null;
+    requireCancelReason?: boolean | null;
+    cancelAtPeriodEndOnly?: boolean | null;
+    sendCancellationEmail?: boolean | null;
+    sendPaymentMethodUpdatedEmail?: boolean | null;
+    customSuccessMessage?: string | null;
+    customCancellationMessage?: string | null;
+    customWelcomeText?: string | null;
+}
 
 /**
  * Charges — the core of the Garu API.
@@ -657,13 +749,61 @@ declare class Meta {
 }
 
 /**
- * Products — discover products available to charge.
+ * Per-product portal customization (Garu v0.8.0). Used by B2B2C platforms
+ * that model their professionals/coaches as Products under a single seller
+ * and want per-product branding on the customer payment + portal pages.
+ */
+declare class ProductPortalConfigResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the portal customization for a product. Returns `null` when no
+     * per-product config exists (the product falls back to seller-level
+     * portal config).
+     *
+     * @example
+     * const cfg = await garu.products.portalConfig.get(57);
+     */
+    get(productId: number): Promise<ProductPortalConfig | null>;
+    /**
+     * Create or merge the portal customization (idempotent upsert). Both
+     * `set` and `patch` have the same merge semantics — only fields present
+     * in the body are written, unspecified fields keep their persisted
+     * value. Use `clear` to reset everything.
+     *
+     * @example
+     * await garu.products.portalConfig.set(57, {
+     *   businessName: 'Coach Maria — Corrida & Trilha',
+     *   primaryColor: '#257264',
+     *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+     * });
+     */
+    set(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
+    patch(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    /**
+     * Remove the per-product config. The product falls back to the
+     * seller-level portal config. Returns `{ removed: true }` when a row was
+     * deleted, `{ removed: false }` when there was nothing to remove.
+     *
+     * @example
+     * await garu.products.portalConfig.clear(57);
+     */
+    clear(productId: number): Promise<{
+        removed: boolean;
+    }>;
+}
+/**
+ * Products — discover products available to charge, and customize the
+ * per-product portal experience (v0.8.0).
  *
  * Products are scoped to the seller identified by the API key. The UUID
  * returned here is the same identifier accepted by `charges.create({ productId })`.
  */
 declare class Products {
     private readonly http;
+    /** Per-product portal customization (Garu v0.8.0). */
+    readonly portalConfig: ProductPortalConfigResource;
     constructor(http: HttpClient);
     /**
      * List products for the authenticated seller, with pagination and search.
@@ -931,4 +1071,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PostponeScheduledChargeParams, type Product, type ProductList, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };

package/dist/index.js

@@ -458,11 +458,80 @@ var Meta = class {
 };
 
 // src/resources/products.ts
+var ProductPortalConfigResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Get the portal customization for a product. Returns `null` when no
+   * per-product config exists (the product falls back to seller-level
+   * portal config).
+   *
+   * @example
+   * const cfg = await garu.products.portalConfig.get(57);
+   */
+  async get(productId) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Create or merge the portal customization (idempotent upsert). Both
+   * `set` and `patch` have the same merge semantics — only fields present
+   * in the body are written, unspecified fields keep their persisted
+   * value. Use `clear` to reset everything.
+   *
+   * @example
+   * await garu.products.portalConfig.set(57, {
+   *   businessName: 'Coach Maria — Corrida & Trilha',
+   *   primaryColor: '#257264',
+   *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+   * });
+   */
+  async set(productId, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/products/${productId}/portal-config`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
+  async patch(productId, params) {
+    return this.http.call(
+      (signal) => this.http.client.PATCH(`/api/products/${productId}/portal-config`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Remove the per-product config. The product falls back to the
+   * seller-level portal config. Returns `{ removed: true }` when a row was
+   * deleted, `{ removed: false }` when there was nothing to remove.
+   *
+   * @example
+   * await garu.products.portalConfig.clear(57);
+   */
+  async clear(productId) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+};
 var Products = class {
   constructor(http) {
     this.http = http;
+    this.portalConfig = new ProductPortalConfigResource(http);
   }
   http;
+  /** Per-product portal customization (Garu v0.8.0). */
+  portalConfig;
   /**
    * List products for the authenticated seller, with pagination and search.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garuhq/node",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",