@fragmentpay/server 0.3.4 → 0.4.0

package/dist/index.d.mts

@@ -23,7 +23,23 @@ declare class FragValidationError extends Error {
 type Chain = "solana" | "ethereum" | "base" | "arbitrum" | "optimism" | "polygon" | "bnb";
 type IntentStatus = "created" | "requires_payment" | "quoted" | "awaiting_signature" | "executing" | "partially_filled" | "settled" | "failed" | "expired" | "cancelled" | "refunded";
 type PayoutStatus = "queued" | "pending" | "paid" | "failed" | "paused";
-type RefundStatus = "pending" | "paid" | "failed" | "cancelled";
+/**
+ * Raw refund status as stored on the backend. See {@link refundPhase} for a
+ * simplified 4-state bucket (`queued | sent | completed | failed`) suitable
+ * for rendering merchant/customer-facing status pills.
+ */
+type RefundStatus = "pending" | "processing" | "retry_scheduled" | "succeeded" | "failed";
+/** UI-friendly refund bucket. */
+type RefundPhase = "queued" | "sent" | "completed" | "failed";
+/**
+ * Map a raw {@link RefundStatus} onto a stable 4-bucket UI phase.
+ *
+ * - `queued`    → `pending` | `retry_scheduled` (waiting to dispatch / retry)
+ * - `sent`      → `processing` (broadcast on-chain / to payout provider, awaiting confirmation)
+ * - `completed` → `succeeded`  (funds delivered, `paid_at` set, `tx_hash` present on-chain rails)
+ * - `failed`    → `failed`     (permanent — retry budget exhausted)
+ */
+declare function refundPhase(status: RefundStatus | string | null | undefined): RefundPhase;
 interface Settlement {
     chain: Chain | string;
     token: string;
@@ -87,16 +103,59 @@ interface Refund {
     id: string;
     payment_intent_id: string;
     amount_usd: number;
-    chain: string;
-    token: string;
+    chain: string | null;
+    token: string | null;
+    /**
+     * Payout address. May be `""` when a refund was auto-enqueued (e.g. by the
+     * expiry sweeper) and Frag has not yet resolved the payer's originating
+     * address. In that case `failure_reason` is `"missing_destination"` and the
+     * refund waits until the merchant supplies one, or Frag derives it from a
+     * confirmed payer leg.
+     */
     destination: string;
     reason: string;
+    /** Raw backend status. Use {@link refundPhase} to bucket for UI. */
     status: RefundStatus;
+    /** On-chain hash once the refund broadcasts. `null` until then. */
     tx_hash: string | null;
+    /** Number of dispatch attempts already made against this refund. */
+    attempts: number;
+    /** ISO timestamp of the next scheduled retry (only set in `retry_scheduled`). */
+    next_attempt_at: string | null;
+    /** ISO timestamp when the refund settled. `null` until `status="succeeded"`. */
+    paid_at: string | null;
+    /** Optional payer email captured at intent time. */
+    customer_email?: string | null;
     created_at: string;
     updated_at: string;
     failure_reason?: string | null;
 }
+/**
+ * Public payer-facing refund status returned by {@link RefundResource.status}.
+ * UNAUTHENTICATED — safe to render on a receipt page or email. `destination`
+ * is redacted to the last 6 chars via `destination_tail`. `phase` is a
+ * stable 4-bucket categorization computed with {@link refundPhase}.
+ */
+interface PublicRefundStatus {
+    id: string;
+    payment_intent_id: string;
+    amount_usd: number;
+    chain: string | null;
+    token: string | null;
+    destination_tail: string;
+    reason: string;
+    status: RefundStatus;
+    /** UI bucket: `queued | sent | completed | failed`. */
+    phase: RefundPhase;
+    tx_hash: string | null;
+    failure_reason: string | null;
+    attempts: number;
+    created_at: string;
+    updated_at: string;
+    paid_at: string | null;
+    /** `true` once no further state change is possible (`completed` or `failed`). */
+    terminal: boolean;
+}
 interface Payout {
     id: string;
     payment_intent_id: string | null;
@@ -170,7 +229,23 @@ declare class FragmentPay {
     readonly webhookEndpoints: WebhookEndpointResource;
     readonly webhooks: WebhookHelpers;
     readonly tokens: TokenResource;
+    readonly checkout: PublicCheckoutResource;
     constructor(opts: FragOptions);
+    /**
+     * Unauthenticated health probe against the API host. Safe to call from
+     * uptime monitors and CI. Returns `{ status: "ok" | "degraded" | "down", ... }`.
+     */
+    health(): Promise<{
+        status: "ok" | "degraded" | "down";
+        service: string;
+        version: string;
+        time: string;
+        latency_ms: number;
+        checks: {
+            env: Record<string, boolean>;
+            database: "ok" | "degraded" | "down";
+        };
+    }>;
     setDebug(on: boolean): void;
 }
 declare class PaymentIntentResource {
@@ -202,13 +277,20 @@ declare class RefundResource {
     create(input: {
         paymentIntentId: string;
         amountUsd: number;
-        destination: string;
+        /**
+         * Payer address to refund to. Optional — omit to let Frag auto-fill from
+         * the intent's confirmed payer leg(s). If no payer address can be derived
+         * the refund is created in `pending` with `failure_reason: "missing_destination"`
+         * until the merchant provides one from the dashboard.
+         */
+        destination?: string;
         reason?: string;
         idempotencyKey?: string;
     }): Promise<Refund>;
     retrieve(id: string): Promise<Refund>;
     list(params?: {
         paymentIntentId?: string;
+        status?: RefundStatus;
         limit?: number;
     }): Promise<{
         data: Refund[];
@@ -216,24 +298,32 @@ declare class RefundResource {
     /**
      * Fetch the payer-facing safe status view for a refund. UNAUTHENTICATED —
      * safe to expose in a customer-facing page or email. Redacts the destination
-     * address (only the last 6 chars) and omits merchant PII.
+     * address (only the last 6 chars) and omits merchant PII. The returned
+     * `phase` field is a stable 4-bucket categorization
+     * (`queued | sent | completed | failed`) computed on the client for
+     * convenient status pills.
      */
-    status(id: string): Promise<{
+    status(id: string): Promise<PublicRefundStatus>;
+    /** Client-side helper: bucket a raw {@link RefundStatus} to a UI phase. */
+    phase(status: RefundStatus | string | null | undefined): RefundPhase;
+}
+/**
+ * Unauthenticated public checkout view used by hosted checkout pages and the
+ * @fragmentpay/react polling hook. Exposes only non-PII fields — no merchant
+ * data, no keys, no idempotency records. Rate-limited to 120 req/min per IP.
+ */
+declare class PublicCheckoutResource {
+    private req;
+    constructor(req: Requester);
+    retrieve(id: string): Promise<{
         id: string;
-        payment_intent_id: string;
-        amount_usd: number;
-        chain: string | null;
-        token: string | null;
-        destination_tail: string;
-        reason: string;
-        status: RefundStatus;
-        tx_hash: string | null;
-        failure_reason: string | null;
-        attempts: number;
-        created_at: string;
-        updated_at: string;
-        paid_at: string | null;
-        terminal: boolean;
+        amount: string;
+        currency: string;
+        status: IntentStatus;
+        settlement_chain: string | null;
+        settlement_token: string | null;
+        expires_at: string;
+        metadata?: Record<string, unknown>;
     }>;
 }
 declare class PayoutResource {
@@ -306,4 +396,4 @@ declare class Frag extends FragmentPay {
     });
 }
 
-export { type Chain, type CreateIntentInput, Frag, FragError, type FragOptions, type FragToken, FragValidationError, FragmentPay, type IntentStatus, type IntentTransaction, type PaymentIntent, type Payout, type PayoutStatus, type Refund, type RefundStatus, type RouteCandidate, type Settlement, type VerifyWebhookInput, type WebhookEndpoint, type WebhookEvent, type WebhookEventType, verifyWebhook };
+export { type Chain, type CreateIntentInput, Frag, FragError, type FragOptions, type FragToken, FragValidationError, FragmentPay, type IntentStatus, type IntentTransaction, type PaymentIntent, type Payout, type PayoutStatus, type PublicRefundStatus, type Refund, type RefundPhase, type RefundStatus, type RouteCandidate, type Settlement, type VerifyWebhookInput, type WebhookEndpoint, type WebhookEvent, type WebhookEventType, refundPhase, verifyWebhook };

package/dist/index.d.ts

@@ -23,7 +23,23 @@ declare class FragValidationError extends Error {
 type Chain = "solana" | "ethereum" | "base" | "arbitrum" | "optimism" | "polygon" | "bnb";
 type IntentStatus = "created" | "requires_payment" | "quoted" | "awaiting_signature" | "executing" | "partially_filled" | "settled" | "failed" | "expired" | "cancelled" | "refunded";
 type PayoutStatus = "queued" | "pending" | "paid" | "failed" | "paused";
-type RefundStatus = "pending" | "paid" | "failed" | "cancelled";
+/**
+ * Raw refund status as stored on the backend. See {@link refundPhase} for a
+ * simplified 4-state bucket (`queued | sent | completed | failed`) suitable
+ * for rendering merchant/customer-facing status pills.
+ */
+type RefundStatus = "pending" | "processing" | "retry_scheduled" | "succeeded" | "failed";
+/** UI-friendly refund bucket. */
+type RefundPhase = "queued" | "sent" | "completed" | "failed";
+/**
+ * Map a raw {@link RefundStatus} onto a stable 4-bucket UI phase.
+ *
+ * - `queued`    → `pending` | `retry_scheduled` (waiting to dispatch / retry)
+ * - `sent`      → `processing` (broadcast on-chain / to payout provider, awaiting confirmation)
+ * - `completed` → `succeeded`  (funds delivered, `paid_at` set, `tx_hash` present on-chain rails)
+ * - `failed`    → `failed`     (permanent — retry budget exhausted)
+ */
+declare function refundPhase(status: RefundStatus | string | null | undefined): RefundPhase;
 interface Settlement {
     chain: Chain | string;
     token: string;
@@ -87,16 +103,59 @@ interface Refund {
     id: string;
     payment_intent_id: string;
     amount_usd: number;
-    chain: string;
-    token: string;
+    chain: string | null;
+    token: string | null;
+    /**
+     * Payout address. May be `""` when a refund was auto-enqueued (e.g. by the
+     * expiry sweeper) and Frag has not yet resolved the payer's originating
+     * address. In that case `failure_reason` is `"missing_destination"` and the
+     * refund waits until the merchant supplies one, or Frag derives it from a
+     * confirmed payer leg.
+     */
     destination: string;
     reason: string;
+    /** Raw backend status. Use {@link refundPhase} to bucket for UI. */
     status: RefundStatus;
+    /** On-chain hash once the refund broadcasts. `null` until then. */
     tx_hash: string | null;
+    /** Number of dispatch attempts already made against this refund. */
+    attempts: number;
+    /** ISO timestamp of the next scheduled retry (only set in `retry_scheduled`). */
+    next_attempt_at: string | null;
+    /** ISO timestamp when the refund settled. `null` until `status="succeeded"`. */
+    paid_at: string | null;
+    /** Optional payer email captured at intent time. */
+    customer_email?: string | null;
     created_at: string;
     updated_at: string;
     failure_reason?: string | null;
 }
+/**
+ * Public payer-facing refund status returned by {@link RefundResource.status}.
+ * UNAUTHENTICATED — safe to render on a receipt page or email. `destination`
+ * is redacted to the last 6 chars via `destination_tail`. `phase` is a
+ * stable 4-bucket categorization computed with {@link refundPhase}.
+ */
+interface PublicRefundStatus {
+    id: string;
+    payment_intent_id: string;
+    amount_usd: number;
+    chain: string | null;
+    token: string | null;
+    destination_tail: string;
+    reason: string;
+    status: RefundStatus;
+    /** UI bucket: `queued | sent | completed | failed`. */
+    phase: RefundPhase;
+    tx_hash: string | null;
+    failure_reason: string | null;
+    attempts: number;
+    created_at: string;
+    updated_at: string;
+    paid_at: string | null;
+    /** `true` once no further state change is possible (`completed` or `failed`). */
+    terminal: boolean;
+}
 interface Payout {
     id: string;
     payment_intent_id: string | null;
@@ -170,7 +229,23 @@ declare class FragmentPay {
     readonly webhookEndpoints: WebhookEndpointResource;
     readonly webhooks: WebhookHelpers;
     readonly tokens: TokenResource;
+    readonly checkout: PublicCheckoutResource;
     constructor(opts: FragOptions);
+    /**
+     * Unauthenticated health probe against the API host. Safe to call from
+     * uptime monitors and CI. Returns `{ status: "ok" | "degraded" | "down", ... }`.
+     */
+    health(): Promise<{
+        status: "ok" | "degraded" | "down";
+        service: string;
+        version: string;
+        time: string;
+        latency_ms: number;
+        checks: {
+            env: Record<string, boolean>;
+            database: "ok" | "degraded" | "down";
+        };
+    }>;
     setDebug(on: boolean): void;
 }
 declare class PaymentIntentResource {
@@ -202,13 +277,20 @@ declare class RefundResource {
     create(input: {
         paymentIntentId: string;
         amountUsd: number;
-        destination: string;
+        /**
+         * Payer address to refund to. Optional — omit to let Frag auto-fill from
+         * the intent's confirmed payer leg(s). If no payer address can be derived
+         * the refund is created in `pending` with `failure_reason: "missing_destination"`
+         * until the merchant provides one from the dashboard.
+         */
+        destination?: string;
         reason?: string;
         idempotencyKey?: string;
     }): Promise<Refund>;
     retrieve(id: string): Promise<Refund>;
     list(params?: {
         paymentIntentId?: string;
+        status?: RefundStatus;
         limit?: number;
     }): Promise<{
         data: Refund[];
@@ -216,24 +298,32 @@ declare class RefundResource {
     /**
      * Fetch the payer-facing safe status view for a refund. UNAUTHENTICATED —
      * safe to expose in a customer-facing page or email. Redacts the destination
-     * address (only the last 6 chars) and omits merchant PII.
+     * address (only the last 6 chars) and omits merchant PII. The returned
+     * `phase` field is a stable 4-bucket categorization
+     * (`queued | sent | completed | failed`) computed on the client for
+     * convenient status pills.
      */
-    status(id: string): Promise<{
+    status(id: string): Promise<PublicRefundStatus>;
+    /** Client-side helper: bucket a raw {@link RefundStatus} to a UI phase. */
+    phase(status: RefundStatus | string | null | undefined): RefundPhase;
+}
+/**
+ * Unauthenticated public checkout view used by hosted checkout pages and the
+ * @fragmentpay/react polling hook. Exposes only non-PII fields — no merchant
+ * data, no keys, no idempotency records. Rate-limited to 120 req/min per IP.
+ */
+declare class PublicCheckoutResource {
+    private req;
+    constructor(req: Requester);
+    retrieve(id: string): Promise<{
         id: string;
-        payment_intent_id: string;
-        amount_usd: number;
-        chain: string | null;
-        token: string | null;
-        destination_tail: string;
-        reason: string;
-        status: RefundStatus;
-        tx_hash: string | null;
-        failure_reason: string | null;
-        attempts: number;
-        created_at: string;
-        updated_at: string;
-        paid_at: string | null;
-        terminal: boolean;
+        amount: string;
+        currency: string;
+        status: IntentStatus;
+        settlement_chain: string | null;
+        settlement_token: string | null;
+        expires_at: string;
+        metadata?: Record<string, unknown>;
     }>;
 }
 declare class PayoutResource {
@@ -306,4 +396,4 @@ declare class Frag extends FragmentPay {
     });
 }
 
-export { type Chain, type CreateIntentInput, Frag, FragError, type FragOptions, type FragToken, FragValidationError, FragmentPay, type IntentStatus, type IntentTransaction, type PaymentIntent, type Payout, type PayoutStatus, type Refund, type RefundStatus, type RouteCandidate, type Settlement, type VerifyWebhookInput, type WebhookEndpoint, type WebhookEvent, type WebhookEventType, verifyWebhook };
+export { type Chain, type CreateIntentInput, Frag, FragError, type FragOptions, type FragToken, FragValidationError, FragmentPay, type IntentStatus, type IntentTransaction, type PaymentIntent, type Payout, type PayoutStatus, type PublicRefundStatus, type Refund, type RefundPhase, type RefundStatus, type RouteCandidate, type Settlement, type VerifyWebhookInput, type WebhookEndpoint, type WebhookEvent, type WebhookEventType, refundPhase, verifyWebhook };

package/dist/index.js

@@ -24,6 +24,7 @@ __export(index_exports, {
   FragError: () => FragError,
   FragValidationError: () => FragValidationError,
   FragmentPay: () => FragmentPay,
+  refundPhase: () => refundPhase,
   verifyWebhook: () => verifyWebhook
 });
 module.exports = __toCommonJS(index_exports);
@@ -118,6 +119,13 @@ var INTENT_STATUSES = [
   "refunded"
 ];
 var PAYOUT_STATUSES = ["queued", "pending", "paid", "failed", "paused"];
+var REFUND_STATUSES = [
+  "pending",
+  "processing",
+  "retry_scheduled",
+  "succeeded",
+  "failed"
+];
 var WEBHOOK_EVENTS = [
   "payment_intent.created",
   "payment_intent.quoted",
@@ -139,6 +147,18 @@ var WEBHOOK_EVENTS = [
 ];
 
 // src/index.ts
+function refundPhase(status) {
+  switch (status) {
+    case "succeeded":
+      return "completed";
+    case "processing":
+      return "sent";
+    case "failed":
+      return "failed";
+    default:
+      return "queued";
+  }
+}
 var FragError = class extends Error {
   status;
   code;
@@ -160,6 +180,7 @@ var FragmentPay = class {
   webhookEndpoints;
   webhooks;
   tokens;
+  checkout;
   #opts;
   constructor(opts) {
     if (!opts || typeof opts !== "object") {
@@ -178,7 +199,7 @@ var FragmentPay = class {
       v.num("options.retries", opts.retries, { min: 0, max: 10, int: true });
     this.#opts = {
       apiKey: opts.apiKey,
-      baseUrl: (opts.baseUrl ?? "https://api.frag.dev").replace(/\/$/, ""),
+      baseUrl: (opts.baseUrl ?? "https://frag.cash").replace(/\/$/, ""),
       fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
       timeout: opts.timeout ?? 3e4,
       retries: opts.retries ?? 2,
@@ -190,8 +211,16 @@ var FragmentPay = class {
     this.payouts = new PayoutResource(req);
     this.webhookEndpoints = new WebhookEndpointResource(req);
     this.tokens = new TokenResource(req);
+    this.checkout = new PublicCheckoutResource(req);
     this.webhooks = new WebhookHelpers();
   }
+  /**
+   * Unauthenticated health probe against the API host. Safe to call from
+   * uptime monitors and CI. Returns `{ status: "ok" | "degraded" | "down", ... }`.
+   */
+  health() {
+    return this.#req(`/api/public/health`, { skipAuth: true });
+  }
   setDebug(on) {
     this.#opts.debug = on;
   }
@@ -355,7 +384,7 @@ var RefundResource = class {
       throw new FragValidationError("refunds.create", "expected object");
     v.id("refunds.create.paymentIntentId", input.paymentIntentId);
     v.num("refunds.create.amountUsd", input.amountUsd, { min: 0.01, max: 1e7 });
-    v.str("refunds.create.destination", input.destination, { min: 26, max: 128 });
+    v.optStr("refunds.create.destination", input.destination, { min: 26, max: 128 });
     v.optStr("refunds.create.reason", input.reason, { max: 500 });
     v.optStr("refunds.create.idempotencyKey", input.idempotencyKey, { min: 8, max: 128 });
     return this.req("/api/public/v1/refunds", {
@@ -376,21 +405,45 @@ var RefundResource = class {
   list(params = {}) {
     if (params.paymentIntentId !== void 0)
       v.id("refunds.list.paymentIntentId", params.paymentIntentId);
+    v.optEnum("refunds.list.status", params.status, REFUND_STATUSES);
     v.optNum("refunds.list.limit", params.limit, { min: 1, max: 100, int: true });
     return this.req(`/api/public/v1/refunds`, {
-      query: { payment_intent_id: params.paymentIntentId, limit: params.limit }
+      query: {
+        payment_intent_id: params.paymentIntentId,
+        status: params.status,
+        limit: params.limit
+      }
     });
   }
   /**
    * Fetch the payer-facing safe status view for a refund. UNAUTHENTICATED —
    * safe to expose in a customer-facing page or email. Redacts the destination
-   * address (only the last 6 chars) and omits merchant PII.
+   * address (only the last 6 chars) and omits merchant PII. The returned
+   * `phase` field is a stable 4-bucket categorization
+   * (`queued | sent | completed | failed`) computed on the client for
+   * convenient status pills.
    */
-  status(id) {
+  async status(id) {
     v.id("refunds.status.id", id);
-    return this.req(`/api/public/refunds/${encodeURIComponent(id)}/status`, {
-      skipAuth: true
-    });
+    const raw = await this.req(
+      `/api/public/refunds/${encodeURIComponent(id)}/status`,
+      { skipAuth: true }
+    );
+    return { ...raw, phase: refundPhase(raw.status) };
+  }
+  /** Client-side helper: bucket a raw {@link RefundStatus} to a UI phase. */
+  phase(status) {
+    return refundPhase(status);
+  }
+};
+var PublicCheckoutResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  req;
+  retrieve(id) {
+    v.id("checkout.retrieve.id", id);
+    return this.req(`/api/public/v1/checkout/${encodeURIComponent(id)}`, { skipAuth: true });
   }
 };
 var PayoutResource = class {
@@ -559,5 +612,6 @@ function timingSafeEqualHex(a, b) {
   FragError,
   FragValidationError,
   FragmentPay,
+  refundPhase,
   verifyWebhook
 });

package/dist/index.mjs

@@ -88,6 +88,13 @@ var INTENT_STATUSES = [
   "refunded"
 ];
 var PAYOUT_STATUSES = ["queued", "pending", "paid", "failed", "paused"];
+var REFUND_STATUSES = [
+  "pending",
+  "processing",
+  "retry_scheduled",
+  "succeeded",
+  "failed"
+];
 var WEBHOOK_EVENTS = [
   "payment_intent.created",
   "payment_intent.quoted",
@@ -109,6 +116,18 @@ var WEBHOOK_EVENTS = [
 ];
 
 // src/index.ts
+function refundPhase(status) {
+  switch (status) {
+    case "succeeded":
+      return "completed";
+    case "processing":
+      return "sent";
+    case "failed":
+      return "failed";
+    default:
+      return "queued";
+  }
+}
 var FragError = class extends Error {
   status;
   code;
@@ -130,6 +149,7 @@ var FragmentPay = class {
   webhookEndpoints;
   webhooks;
   tokens;
+  checkout;
   #opts;
   constructor(opts) {
     if (!opts || typeof opts !== "object") {
@@ -148,7 +168,7 @@ var FragmentPay = class {
       v.num("options.retries", opts.retries, { min: 0, max: 10, int: true });
     this.#opts = {
       apiKey: opts.apiKey,
-      baseUrl: (opts.baseUrl ?? "https://api.frag.dev").replace(/\/$/, ""),
+      baseUrl: (opts.baseUrl ?? "https://frag.cash").replace(/\/$/, ""),
       fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
       timeout: opts.timeout ?? 3e4,
       retries: opts.retries ?? 2,
@@ -160,8 +180,16 @@ var FragmentPay = class {
     this.payouts = new PayoutResource(req);
     this.webhookEndpoints = new WebhookEndpointResource(req);
     this.tokens = new TokenResource(req);
+    this.checkout = new PublicCheckoutResource(req);
     this.webhooks = new WebhookHelpers();
   }
+  /**
+   * Unauthenticated health probe against the API host. Safe to call from
+   * uptime monitors and CI. Returns `{ status: "ok" | "degraded" | "down", ... }`.
+   */
+  health() {
+    return this.#req(`/api/public/health`, { skipAuth: true });
+  }
   setDebug(on) {
     this.#opts.debug = on;
   }
@@ -325,7 +353,7 @@ var RefundResource = class {
       throw new FragValidationError("refunds.create", "expected object");
     v.id("refunds.create.paymentIntentId", input.paymentIntentId);
     v.num("refunds.create.amountUsd", input.amountUsd, { min: 0.01, max: 1e7 });
-    v.str("refunds.create.destination", input.destination, { min: 26, max: 128 });
+    v.optStr("refunds.create.destination", input.destination, { min: 26, max: 128 });
     v.optStr("refunds.create.reason", input.reason, { max: 500 });
     v.optStr("refunds.create.idempotencyKey", input.idempotencyKey, { min: 8, max: 128 });
     return this.req("/api/public/v1/refunds", {
@@ -346,21 +374,45 @@ var RefundResource = class {
   list(params = {}) {
     if (params.paymentIntentId !== void 0)
       v.id("refunds.list.paymentIntentId", params.paymentIntentId);
+    v.optEnum("refunds.list.status", params.status, REFUND_STATUSES);
     v.optNum("refunds.list.limit", params.limit, { min: 1, max: 100, int: true });
     return this.req(`/api/public/v1/refunds`, {
-      query: { payment_intent_id: params.paymentIntentId, limit: params.limit }
+      query: {
+        payment_intent_id: params.paymentIntentId,
+        status: params.status,
+        limit: params.limit
+      }
     });
   }
   /**
    * Fetch the payer-facing safe status view for a refund. UNAUTHENTICATED —
    * safe to expose in a customer-facing page or email. Redacts the destination
-   * address (only the last 6 chars) and omits merchant PII.
+   * address (only the last 6 chars) and omits merchant PII. The returned
+   * `phase` field is a stable 4-bucket categorization
+   * (`queued | sent | completed | failed`) computed on the client for
+   * convenient status pills.
    */
-  status(id) {
+  async status(id) {
     v.id("refunds.status.id", id);
-    return this.req(`/api/public/refunds/${encodeURIComponent(id)}/status`, {
-      skipAuth: true
-    });
+    const raw = await this.req(
+      `/api/public/refunds/${encodeURIComponent(id)}/status`,
+      { skipAuth: true }
+    );
+    return { ...raw, phase: refundPhase(raw.status) };
+  }
+  /** Client-side helper: bucket a raw {@link RefundStatus} to a UI phase. */
+  phase(status) {
+    return refundPhase(status);
+  }
+};
+var PublicCheckoutResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  req;
+  retrieve(id) {
+    v.id("checkout.retrieve.id", id);
+    return this.req(`/api/public/v1/checkout/${encodeURIComponent(id)}`, { skipAuth: true });
   }
 };
 var PayoutResource = class {
@@ -528,5 +580,6 @@ export {
   FragError,
   FragValidationError,
   FragmentPay,
+  refundPhase,
   verifyWebhook
 };