Node.js SDK

import { Carden } from "@carden/node";

const carden = new Carden({
  apiKey: process.env.CARDEN_API_KEY!,
  baseUrl: process.env.CARDEN_BASE_URL!,
  timeoutMs: 5000,
});

// invoice is the complete CanonicalInvoice from your trusted invoice source.
const { enrichment, requestId } = await carden.stripe.createPaymentIntentEnrichmentWithRequestId({
  invoice,
  options: { taxRepresentation: "line_item", discountRepresentation: "line_item" },
});

// Persist requestId with your attempt; omit enrichmentRequestId if it is null.
// enrichment contains amount_details and payment_details, not a PaymentIntent.
// Merge these fields into your own supported Stripe request on your server.
// Keep Stripe authentication and payment idempotency in your existing backend.
// Persist and deliver the actual outcome separately with the payment-report API.

// In your durable outbox worker. carden is the configured server client.
// report is the immutable, validated event previously persisted by your backend.
const receipt = await carden.stripe.reportPayment(report, {
  maxRetries: 0, // The durable worker owns backoff and respects rate-limit delays.
  timeoutMs: 5000,
});
// receipt is { id: string, duplicate: boolean }, not the HTTP envelope.
// Mark the outbox entry delivered for either duplicate value.
// On error, retain the same eventId and payload; never repeat the Stripe charge.

// Run in a server worker. report is the immutable payload saved in your outbox.
// baseUrl is your Carden deployment origin; apiKey is a scoped Carden key.
const response = await fetch(new URL("/api/v1/stripe/payment-reports", baseUrl), {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(report),
  signal: AbortSignal.timeout(5000),
});
const requestId = response.headers.get("x-carden-request-id");
const payload = await response.json();
if (!response.ok) {
  // Record status and requestId; retry this report or alert on permanent errors.
  // Never repeat the Stripe payment because this request failed.
  throw new Error(`Carden report failed: ${response.status} (${requestId})`);
}
if (payload?.object !== "stripe.payment_report" || payload.api_version !== "v1" ||
    typeof payload.data?.id !== "string" || !payload.data.id ||
    typeof payload.data?.duplicate !== "boolean") {
  throw new Error("Unexpected Carden report response; retain the outbox entry");
}
// Mark this outbox entry delivered, including when data.duplicate is true.
// Persist payload.data.id for reconciliation.

import { paymentObservationFromStripePaymentIntent } from "@carden/node";

// Prerequisites supplied by your backend:
// - carden: a server client with a Stripe-integration Carden key.
// - attempt: a durably stored attempt with stable eventId/attemptId, currency,
//   amountMinor, known capturedAmountMinor/refundedAmountMinor, and invoiceReference.
// - executeStripePayment: your existing operation with your Stripe idempotency policy.
//   It returns a PaymentIntent with an expanded latest_charge for refund evidence.
// - reportDeliveryMonitor: your application's safe operational alerting adapter.
const result = await carden.stripe.trackPayment(executeStripePayment, {
  report: {
    eventId: attempt.eventId,
    attemptId: attempt.attemptId,
    currency: attempt.currency,
    amountMinor: attempt.amountMinor,
    capturedAmountMinor: attempt.capturedAmountMinor,
    refundedAmountMinor: attempt.refundedAmountMinor,
    invoiceReference: attempt.invoiceReference,
    ...(requestId ? { enrichmentRequestId: requestId } : {}),
  },
  selectResult: (intent) => paymentObservationFromStripePaymentIntent(intent),
  reportOptions: { maxRetries: 0, timeoutMs: 1000 },
  onReportError: (error, { report }) => {
    // Monitoring only: this callback is not a durable-delivery guarantee.
    // report is null if selection/validation failed; never log raw Stripe errors.
    reportDeliveryMonitor.record({
      attemptId: attempt.attemptId,
      eventId: report?.eventId ?? attempt.eventId,
      errorType: error.name,
    });
  },
});
// result is the original Stripe result, even when Carden reporting failed.
// Your durable reconciliation/outbox process must recover undelivered reports.
// A provider exception is rethrown unchanged; it is not automatically a failure status.

import { paymentObservationFromStripePaymentIntent } from "@carden/node";

// intent is a verified/retrieved provider snapshot kept in your own backend.
// Prefer an expanded latest_charge with actual amount_captured and amount_refunded.
const observation = paymentObservationFromStripePaymentIntent(intent);

// If latest_charge is not expanded, provide a separately known refund total:
// paymentObservationFromStripePaymentIntent(intent, { refundedAmountMinor: knownRefundTotal });
// Never substitute zero for a refund total you have not established.

// Combine observation with your stable eventId/attemptId, actual occurredAt,
// source: "merchant_webhook", and verified providerEventId where applicable.
// Persist the resulting report first, then deliver it via reportPayment.
// This helper performs no network request and does not verify the Stripe signature.