@fragmentpay/server 0.3.1 → 0.3.4

package/README.md

@@ -17,11 +17,11 @@ npm install @fragmentpay/server
 
 ## Required environment variables
 
-| Name                     | Where          | Example                                 |
-| ------------------------ | -------------- | --------------------------------------- |
-| `FRAG_SECRET_KEY`        | server only    | `sk_live_…` or `sk_test_…`              |
-| `FRAG_WEBHOOK_SECRET`    | server only    | value shown when you create the webhook |
-| `FRAG_BASE_URL` *(opt.)* | server only    | override host, default `https://api.frag.dev` |
+| Name                     | Where       | Example                                    |
+| ------------------------ | ----------- | ------------------------------------------ |
+| `FRAG_SECRET_KEY`        | server only | `sk_live_…` or `sk_test_…`                 |
+| `FRAG_WEBHOOK_SECRET`    | server only | value shown when you create the webhook    |
+| `FRAG_BASE_URL` _(opt.)_ | server only | override host, default `https://frag.cash` |
 
 Never expose `sk_…` in a browser bundle.
 
@@ -46,7 +46,7 @@ export async function startCheckout(orderId: string, cents: number, email: strin
       address: process.env.MERCHANT_USDC_ADDRESS!,
     },
     successUrl: "https://shop.example.com/thanks",
-    cancelUrl:  "https://shop.example.com/cart",
+    cancelUrl: "https://shop.example.com/cart",
     metadata: { order_id: orderId },
     idempotencyKey: `order_${orderId}`,
   });
@@ -64,7 +64,7 @@ export async function POST(req: Request) {
   const payload = await req.text();
   const event = await verifyWebhook({
     payload,
-    signature: req.headers.get("x-frag-signature"),
+    signature: req.headers.get("frag-signature"),
     secret: process.env.FRAG_WEBHOOK_SECRET!,
   });
 
@@ -77,6 +77,22 @@ export async function POST(req: Request) {
 
 **3. React drop-in on the frontend** — see `@fragmentpay/react`.
 
+## Advanced options
+
+```ts
+const frag = new Frag({
+  secretKey: process.env.FRAG_SECRET_KEY!,
+  baseUrl: "https://frag.cash", // default
+  timeoutMs: 15_000, // per-request timeout
+  maxRetries: 3, // retries on 5xx / network errors with Retry-After honored
+  fetch: myCustomFetch, // inject a custom fetch (Workers, tracing, etc.)
+});
+```
+
+Every method throws `FragError` on non-2xx responses. It carries `status`,
+`code`, `message`, and `requestId` for observability, plus the raw provider
+body when available.
+
 ## Validation errors
 
 Every method validates its arguments and throws a `FragValidationError`
@@ -89,7 +105,8 @@ frag.paymentIntents.create({ amount: -5 });
 
 ## Public API surface
 
-- `frag.paymentIntents.{create, retrieve, list, cancel, transactions, route}`
+- `frag.paymentIntents.{create, retrieve, list, cancel, transactions, routing}`
+  - `routing(id)` returns router candidates evaluated for the intent (chosen + rejected with reasons). `route(id)` is kept as a deprecated alias.
 - `frag.refunds.{create, retrieve, list}`
 - `frag.payouts.{retrieve, list, replay}`
 - `frag.webhookEndpoints.{create, list, retrieve, update, delete, rotateSecret}`
@@ -97,6 +114,21 @@ frag.paymentIntents.create({ amount: -5 });
 - `verifyWebhook({ payload, signature, secret })`
 - `FragError` (HTTP + upstream) and `FragValidationError` (input)
 
+## Idempotency
+
+Every `POST` accepts an optional `Idempotency-Key` header (SDK auto-sends it
+when you set `idempotencyKey`). Replays within 24h with the **same body**
+return the original response; a **different body** returns HTTP `409` with
+`code: "idempotency_conflict"`.
+
+## Webhook events
+
+The SDK's `WebhookEventType` union stays in sync with the API. Notable events:
+`payment_intent.created`, `payment_intent.quoted`, `payment_intent.executing`,
+`payment_intent.settled`, `payment_intent.failed`, `payment_intent.expired`,
+`payment_intent.cancelled`, `payment_intent.refunded`, `payout.created`,
+`payout.paid`, `payout.failed`, `ping`.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -94,7 +94,7 @@ interface Refund {
     status: RefundStatus;
     tx_hash: string | null;
     created_at: string;
-    paid_at: string | null;
+    updated_at: string;
     failure_reason?: string | null;
 }
 interface Payout {
@@ -132,7 +132,7 @@ interface FragToken {
     verified: boolean;
     min_liquidity_usd?: number;
 }
-type WebhookEventType = "payment_intent.created" | "payment_intent.quoted" | "payment_intent.executing" | "payment_intent.executed" | "payment_intent.settled" | "payment_intent.failed" | "payment_intent.expired" | "payment_intent.cancelled" | "payment_intent.refunded" | "quote.created" | "settlement.confirmed" | "payout.pending" | "payout.paid" | "payout.failed" | "refund.pending" | "refund.paid" | "refund.failed";
+type WebhookEventType = "payment_intent.created" | "payment_intent.quoted" | "payment_intent.executing" | "payment_intent.executed" | "payment_intent.settled" | "payment_intent.failed" | "payment_intent.expired" | "payment_intent.cancelled" | "payment_intent.refunded" | "quote.created" | "settlement.confirmed" | "payout.created" | "payout.paid" | "payout.failed" | "refund.created" | "refund.processing" | "refund.paid" | "refund.failed";
 interface WebhookEvent<T = unknown> {
     id: string;
     type: WebhookEventType;
@@ -160,6 +160,7 @@ declare class FragError extends Error {
 type Requester = <T>(path: string, init?: RequestInit & {
     idempotencyKey?: string;
     query?: Record<string, string | number | boolean | undefined>;
+    skipAuth?: boolean;
 }) => Promise<T>;
 declare class FragmentPay {
     #private;
@@ -212,6 +213,28 @@ declare class RefundResource {
     }): Promise<{
         data: Refund[];
     }>;
+    /**
+     * 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.
+     */
+    status(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;
+    }>;
 }
 declare class PayoutResource {
     private req;

package/dist/index.d.ts

@@ -94,7 +94,7 @@ interface Refund {
     status: RefundStatus;
     tx_hash: string | null;
     created_at: string;
-    paid_at: string | null;
+    updated_at: string;
     failure_reason?: string | null;
 }
 interface Payout {
@@ -132,7 +132,7 @@ interface FragToken {
     verified: boolean;
     min_liquidity_usd?: number;
 }
-type WebhookEventType = "payment_intent.created" | "payment_intent.quoted" | "payment_intent.executing" | "payment_intent.executed" | "payment_intent.settled" | "payment_intent.failed" | "payment_intent.expired" | "payment_intent.cancelled" | "payment_intent.refunded" | "quote.created" | "settlement.confirmed" | "payout.pending" | "payout.paid" | "payout.failed" | "refund.pending" | "refund.paid" | "refund.failed";
+type WebhookEventType = "payment_intent.created" | "payment_intent.quoted" | "payment_intent.executing" | "payment_intent.executed" | "payment_intent.settled" | "payment_intent.failed" | "payment_intent.expired" | "payment_intent.cancelled" | "payment_intent.refunded" | "quote.created" | "settlement.confirmed" | "payout.created" | "payout.paid" | "payout.failed" | "refund.created" | "refund.processing" | "refund.paid" | "refund.failed";
 interface WebhookEvent<T = unknown> {
     id: string;
     type: WebhookEventType;
@@ -160,6 +160,7 @@ declare class FragError extends Error {
 type Requester = <T>(path: string, init?: RequestInit & {
     idempotencyKey?: string;
     query?: Record<string, string | number | boolean | undefined>;
+    skipAuth?: boolean;
 }) => Promise<T>;
 declare class FragmentPay {
     #private;
@@ -212,6 +213,28 @@ declare class RefundResource {
     }): Promise<{
         data: Refund[];
     }>;
+    /**
+     * 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.
+     */
+    status(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;
+    }>;
 }
 declare class PayoutResource {
     private req;

package/dist/index.js

@@ -54,7 +54,8 @@ var v = {
   },
   num(path, val, opts = {}) {
     const n = typeof val === "string" ? Number(val) : val;
-    if (typeof n !== "number" || !Number.isFinite(n)) return fail(path, `expected finite number, got ${JSON.stringify(val)}`);
+    if (typeof n !== "number" || !Number.isFinite(n))
+      return fail(path, `expected finite number, got ${JSON.stringify(val)}`);
     if (opts.int && !Number.isInteger(n)) fail(path, "expected integer");
     if (opts.min != null && n < opts.min) fail(path, `min ${opts.min}`);
     if (opts.max != null && n > opts.max) fail(path, `max ${opts.max}`);
@@ -94,7 +95,15 @@ var v = {
     return v.str(path, val, { max: 254, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ });
   }
 };
-var CHAINS = ["solana", "ethereum", "base", "arbitrum", "optimism", "polygon", "bnb"];
+var CHAINS = [
+  "solana",
+  "ethereum",
+  "base",
+  "arbitrum",
+  "optimism",
+  "polygon",
+  "bnb"
+];
 var INTENT_STATUSES = [
   "created",
   "requires_payment",
@@ -157,11 +166,16 @@ var FragmentPay = class {
       throw new FragValidationError("options", "expected FragOptions object");
     }
     if (typeof opts.apiKey !== "string" || !/^sk_(test|live)_[A-Za-z0-9_-]{8,}$/.test(opts.apiKey)) {
-      throw new FragValidationError("options.apiKey", "must match sk_test_\u2026 or sk_live_\u2026 (min 8 chars after prefix)");
+      throw new FragValidationError(
+        "options.apiKey",
+        "must match sk_test_\u2026 or sk_live_\u2026 (min 8 chars after prefix)"
+      );
     }
     if (opts.baseUrl !== void 0) v.url("options.baseUrl", opts.baseUrl);
-    if (opts.timeout !== void 0) v.num("options.timeout", opts.timeout, { min: 0, max: 6e5, int: true });
-    if (opts.retries !== void 0) v.num("options.retries", opts.retries, { min: 0, max: 10, int: true });
+    if (opts.timeout !== void 0)
+      v.num("options.timeout", opts.timeout, { min: 0, max: 6e5, int: true });
+    if (opts.retries !== void 0)
+      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(/\/$/, ""),
@@ -187,7 +201,7 @@ var FragmentPay = class {
     ).toString() : "";
     const url = `${this.#opts.baseUrl}${path}${query}`;
     const headers = new Headers(init.headers);
-    headers.set("authorization", `Bearer ${this.#opts.apiKey}`);
+    if (!init.skipAuth) headers.set("authorization", `Bearer ${this.#opts.apiKey}`);
     if (init.body && !headers.has("content-type")) headers.set("content-type", "application/json");
     if (init.idempotencyKey) headers.set("idempotency-key", init.idempotencyKey);
     const maxAttempts = Math.max(1, this.#opts.retries + 1);
@@ -251,16 +265,35 @@ var PaymentIntentResource = class {
   }
   req;
   create(input) {
-    if (!input || typeof input !== "object") throw new FragValidationError("createIntent", "expected object");
+    if (!input || typeof input !== "object")
+      throw new FragValidationError("createIntent", "expected object");
     const amount = v.num("createIntent.amount", input.amount, { min: 0.01, max: 1e7 });
-    const currency = v.optStr("createIntent.currency", input.currency, { min: 3, max: 8, pattern: /^[A-Z]{3,8}$/ }) ?? "USD";
+    const currency = v.optStr("createIntent.currency", input.currency, {
+      min: 3,
+      max: 8,
+      pattern: /^[A-Z]{3,8}$/
+    }) ?? "USD";
     if (input.settlement !== void 0) v.obj("createIntent.settlement", input.settlement);
     const settlementChain = input.settlement?.chain ? v.enum("createIntent.settlement.chain", input.settlement.chain, CHAINS) : void 0;
-    const settlementToken = v.optStr("createIntent.settlement.token", input.settlement?.token, { min: 1, max: 64 });
-    const settlementAddress = v.optStr("createIntent.settlement.address", input.settlement?.address, { min: 26, max: 128 });
+    const settlementToken = v.optStr("createIntent.settlement.token", input.settlement?.token, {
+      min: 1,
+      max: 64
+    });
+    const settlementAddress = v.optStr(
+      "createIntent.settlement.address",
+      input.settlement?.address,
+      { min: 26, max: 128 }
+    );
     const customerEmail = input.customerEmail !== void 0 ? v.email("createIntent.customerEmail", input.customerEmail) : void 0;
-    const expiresInSeconds = v.optNum("createIntent.expiresInSeconds", input.expiresInSeconds, { min: 60, max: 86400, int: true });
-    const idempotencyKey = v.optStr("createIntent.idempotencyKey", input.idempotencyKey, { min: 8, max: 128 });
+    const expiresInSeconds = v.optNum("createIntent.expiresInSeconds", input.expiresInSeconds, {
+      min: 60,
+      max: 86400,
+      int: true
+    });
+    const idempotencyKey = v.optStr("createIntent.idempotencyKey", input.idempotencyKey, {
+      min: 8,
+      max: 128
+    });
     const successUrl = input.successUrl !== void 0 ? v.url("createIntent.successUrl", input.successUrl) : void 0;
     const cancelUrl = input.cancelUrl !== void 0 ? v.url("createIntent.cancelUrl", input.cancelUrl) : void 0;
     if (input.metadata !== void 0) v.obj("createIntent.metadata", input.metadata);
@@ -294,7 +327,10 @@ var PaymentIntentResource = class {
   }
   cancel(id) {
     v.id("paymentIntents.cancel.id", id);
-    return this.req(`/api/public/v1/payment-intents/${encodeURIComponent(id)}/cancel`, { method: "POST" });
+    return this.req(
+      `/api/public/v1/payment-intents/${encodeURIComponent(id)}/cancel`,
+      { method: "POST" }
+    );
   }
   transactions(id) {
     v.id("paymentIntents.transactions.id", id);
@@ -315,7 +351,8 @@ var RefundResource = class {
   }
   req;
   create(input) {
-    if (!input || typeof input !== "object") throw new FragValidationError("refunds.create", "expected object");
+    if (!input || typeof input !== "object")
+      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 });
@@ -337,12 +374,24 @@ var RefundResource = class {
     return this.req(`/api/public/v1/refunds/${encodeURIComponent(id)}`);
   }
   list(params = {}) {
-    if (params.paymentIntentId !== void 0) v.id("refunds.list.paymentIntentId", params.paymentIntentId);
+    if (params.paymentIntentId !== void 0)
+      v.id("refunds.list.paymentIntentId", params.paymentIntentId);
     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 }
     });
   }
+  /**
+   * 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.
+   */
+  status(id) {
+    v.id("refunds.status.id", id);
+    return this.req(`/api/public/refunds/${encodeURIComponent(id)}/status`, {
+      skipAuth: true
+    });
+  }
 };
 var PayoutResource = class {
   constructor(req) {
@@ -355,10 +404,15 @@ var PayoutResource = class {
   }
   list(params = {}) {
     v.optEnum("payouts.list.status", params.status, PAYOUT_STATUSES);
-    if (params.paymentIntentId !== void 0) v.id("payouts.list.paymentIntentId", params.paymentIntentId);
+    if (params.paymentIntentId !== void 0)
+      v.id("payouts.list.paymentIntentId", params.paymentIntentId);
     v.optNum("payouts.list.limit", params.limit, { min: 1, max: 100, int: true });
     return this.req(`/api/public/v1/payouts`, {
-      query: { status: params.status, payment_intent_id: params.paymentIntentId, limit: params.limit }
+      query: {
+        status: params.status,
+        payment_intent_id: params.paymentIntentId,
+        limit: params.limit
+      }
     });
   }
   replay(id) {
@@ -372,12 +426,18 @@ var WebhookEndpointResource = class {
   }
   req;
   create(input) {
-    if (!input || typeof input !== "object") throw new FragValidationError("webhookEndpoints.create", "expected object");
+    if (!input || typeof input !== "object")
+      throw new FragValidationError("webhookEndpoints.create", "expected object");
     v.url("webhookEndpoints.create.url", input.url);
     if (!Array.isArray(input.events) || input.events.length === 0) {
-      throw new FragValidationError("webhookEndpoints.create.events", "at least one event required");
+      throw new FragValidationError(
+        "webhookEndpoints.create.events",
+        "at least one event required"
+      );
     }
-    input.events.forEach((e, i) => v.enum(`webhookEndpoints.create.events[${i}]`, e, WEBHOOK_EVENTS));
+    input.events.forEach(
+      (e, i) => v.enum(`webhookEndpoints.create.events[${i}]`, e, WEBHOOK_EVENTS)
+    );
     return this.req("/api/public/v1/webhook-endpoints", {
       method: "POST",
       body: JSON.stringify(input)
@@ -394,8 +454,11 @@ var WebhookEndpointResource = class {
     v.id("webhookEndpoints.update.id", id);
     if (patch.url !== void 0) v.url("webhookEndpoints.update.url", patch.url);
     if (patch.events !== void 0) {
-      if (!Array.isArray(patch.events)) throw new FragValidationError("webhookEndpoints.update.events", "expected array");
-      patch.events.forEach((e, i) => v.enum(`webhookEndpoints.update.events[${i}]`, e, WEBHOOK_EVENTS));
+      if (!Array.isArray(patch.events))
+        throw new FragValidationError("webhookEndpoints.update.events", "expected array");
+      patch.events.forEach(
+        (e, i) => v.enum(`webhookEndpoints.update.events[${i}]`, e, WEBHOOK_EVENTS)
+      );
     }
     return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}`, {
       method: "PATCH",
@@ -404,11 +467,16 @@ var WebhookEndpointResource = class {
   }
   delete(id) {
     v.id("webhookEndpoints.delete.id", id);
-    return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}`, { method: "DELETE" });
+    return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
   }
   rotateSecret(id) {
     v.id("webhookEndpoints.rotateSecret.id", id);
-    return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}/rotate-secret`, { method: "POST" });
+    return this.req(
+      `/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}/rotate-secret`,
+      { method: "POST" }
+    );
   }
 };
 var TokenResource = class {
@@ -438,19 +506,34 @@ var WebhookHelpers = class {
   }
 };
 async function verifyWebhook(input) {
-  if (!input || typeof input !== "object") throw new FragValidationError("verifyWebhook", "expected object");
+  if (!input || typeof input !== "object")
+    throw new FragValidationError("verifyWebhook", "expected object");
   v.str("verifyWebhook.payload", input.payload, { min: 1 });
   v.str("verifyWebhook.secret", input.secret, { min: 8 });
-  if (input.tolerance !== void 0) v.num("verifyWebhook.tolerance", input.tolerance, { min: 0, max: 3600, int: true });
+  if (input.tolerance !== void 0)
+    v.num("verifyWebhook.tolerance", input.tolerance, { min: 0, max: 3600, int: true });
   const helper = new WebhookHelpers();
-  const ok = await helper.verify(input.payload, input.signature ?? null, input.secret, input.tolerance);
-  if (!ok) throw new FragError(401, "invalid_signature", "webhook signature verification failed", null);
+  const ok = await helper.verify(
+    input.payload,
+    input.signature ?? null,
+    input.secret,
+    input.tolerance
+  );
+  if (!ok)
+    throw new FragError(401, "invalid_signature", "webhook signature verification failed", null);
   return helper.parse(input.payload);
 }
 var Frag = class extends FragmentPay {
   constructor(opts) {
     const apiKey = "secretKey" in opts ? opts.secretKey : opts.apiKey;
-    super({ apiKey, baseUrl: opts.baseUrl, fetch: opts.fetch, timeout: opts.timeout, retries: opts.retries, debug: opts.debug });
+    super({
+      apiKey,
+      baseUrl: opts.baseUrl,
+      fetch: opts.fetch,
+      timeout: opts.timeout,
+      retries: opts.retries,
+      debug: opts.debug
+    });
   }
 };
 async function hmacHex(secret, message) {

package/dist/index.mjs

@@ -24,7 +24,8 @@ var v = {
   },
   num(path, val, opts = {}) {
     const n = typeof val === "string" ? Number(val) : val;
-    if (typeof n !== "number" || !Number.isFinite(n)) return fail(path, `expected finite number, got ${JSON.stringify(val)}`);
+    if (typeof n !== "number" || !Number.isFinite(n))
+      return fail(path, `expected finite number, got ${JSON.stringify(val)}`);
     if (opts.int && !Number.isInteger(n)) fail(path, "expected integer");
     if (opts.min != null && n < opts.min) fail(path, `min ${opts.min}`);
     if (opts.max != null && n > opts.max) fail(path, `max ${opts.max}`);
@@ -64,7 +65,15 @@ var v = {
     return v.str(path, val, { max: 254, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ });
   }
 };
-var CHAINS = ["solana", "ethereum", "base", "arbitrum", "optimism", "polygon", "bnb"];
+var CHAINS = [
+  "solana",
+  "ethereum",
+  "base",
+  "arbitrum",
+  "optimism",
+  "polygon",
+  "bnb"
+];
 var INTENT_STATUSES = [
   "created",
   "requires_payment",
@@ -127,11 +136,16 @@ var FragmentPay = class {
       throw new FragValidationError("options", "expected FragOptions object");
     }
     if (typeof opts.apiKey !== "string" || !/^sk_(test|live)_[A-Za-z0-9_-]{8,}$/.test(opts.apiKey)) {
-      throw new FragValidationError("options.apiKey", "must match sk_test_\u2026 or sk_live_\u2026 (min 8 chars after prefix)");
+      throw new FragValidationError(
+        "options.apiKey",
+        "must match sk_test_\u2026 or sk_live_\u2026 (min 8 chars after prefix)"
+      );
     }
     if (opts.baseUrl !== void 0) v.url("options.baseUrl", opts.baseUrl);
-    if (opts.timeout !== void 0) v.num("options.timeout", opts.timeout, { min: 0, max: 6e5, int: true });
-    if (opts.retries !== void 0) v.num("options.retries", opts.retries, { min: 0, max: 10, int: true });
+    if (opts.timeout !== void 0)
+      v.num("options.timeout", opts.timeout, { min: 0, max: 6e5, int: true });
+    if (opts.retries !== void 0)
+      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(/\/$/, ""),
@@ -157,7 +171,7 @@ var FragmentPay = class {
     ).toString() : "";
     const url = `${this.#opts.baseUrl}${path}${query}`;
     const headers = new Headers(init.headers);
-    headers.set("authorization", `Bearer ${this.#opts.apiKey}`);
+    if (!init.skipAuth) headers.set("authorization", `Bearer ${this.#opts.apiKey}`);
     if (init.body && !headers.has("content-type")) headers.set("content-type", "application/json");
     if (init.idempotencyKey) headers.set("idempotency-key", init.idempotencyKey);
     const maxAttempts = Math.max(1, this.#opts.retries + 1);
@@ -221,16 +235,35 @@ var PaymentIntentResource = class {
   }
   req;
   create(input) {
-    if (!input || typeof input !== "object") throw new FragValidationError("createIntent", "expected object");
+    if (!input || typeof input !== "object")
+      throw new FragValidationError("createIntent", "expected object");
     const amount = v.num("createIntent.amount", input.amount, { min: 0.01, max: 1e7 });
-    const currency = v.optStr("createIntent.currency", input.currency, { min: 3, max: 8, pattern: /^[A-Z]{3,8}$/ }) ?? "USD";
+    const currency = v.optStr("createIntent.currency", input.currency, {
+      min: 3,
+      max: 8,
+      pattern: /^[A-Z]{3,8}$/
+    }) ?? "USD";
     if (input.settlement !== void 0) v.obj("createIntent.settlement", input.settlement);
     const settlementChain = input.settlement?.chain ? v.enum("createIntent.settlement.chain", input.settlement.chain, CHAINS) : void 0;
-    const settlementToken = v.optStr("createIntent.settlement.token", input.settlement?.token, { min: 1, max: 64 });
-    const settlementAddress = v.optStr("createIntent.settlement.address", input.settlement?.address, { min: 26, max: 128 });
+    const settlementToken = v.optStr("createIntent.settlement.token", input.settlement?.token, {
+      min: 1,
+      max: 64
+    });
+    const settlementAddress = v.optStr(
+      "createIntent.settlement.address",
+      input.settlement?.address,
+      { min: 26, max: 128 }
+    );
     const customerEmail = input.customerEmail !== void 0 ? v.email("createIntent.customerEmail", input.customerEmail) : void 0;
-    const expiresInSeconds = v.optNum("createIntent.expiresInSeconds", input.expiresInSeconds, { min: 60, max: 86400, int: true });
-    const idempotencyKey = v.optStr("createIntent.idempotencyKey", input.idempotencyKey, { min: 8, max: 128 });
+    const expiresInSeconds = v.optNum("createIntent.expiresInSeconds", input.expiresInSeconds, {
+      min: 60,
+      max: 86400,
+      int: true
+    });
+    const idempotencyKey = v.optStr("createIntent.idempotencyKey", input.idempotencyKey, {
+      min: 8,
+      max: 128
+    });
     const successUrl = input.successUrl !== void 0 ? v.url("createIntent.successUrl", input.successUrl) : void 0;
     const cancelUrl = input.cancelUrl !== void 0 ? v.url("createIntent.cancelUrl", input.cancelUrl) : void 0;
     if (input.metadata !== void 0) v.obj("createIntent.metadata", input.metadata);
@@ -264,7 +297,10 @@ var PaymentIntentResource = class {
   }
   cancel(id) {
     v.id("paymentIntents.cancel.id", id);
-    return this.req(`/api/public/v1/payment-intents/${encodeURIComponent(id)}/cancel`, { method: "POST" });
+    return this.req(
+      `/api/public/v1/payment-intents/${encodeURIComponent(id)}/cancel`,
+      { method: "POST" }
+    );
   }
   transactions(id) {
     v.id("paymentIntents.transactions.id", id);
@@ -285,7 +321,8 @@ var RefundResource = class {
   }
   req;
   create(input) {
-    if (!input || typeof input !== "object") throw new FragValidationError("refunds.create", "expected object");
+    if (!input || typeof input !== "object")
+      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 });
@@ -307,12 +344,24 @@ var RefundResource = class {
     return this.req(`/api/public/v1/refunds/${encodeURIComponent(id)}`);
   }
   list(params = {}) {
-    if (params.paymentIntentId !== void 0) v.id("refunds.list.paymentIntentId", params.paymentIntentId);
+    if (params.paymentIntentId !== void 0)
+      v.id("refunds.list.paymentIntentId", params.paymentIntentId);
     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 }
     });
   }
+  /**
+   * 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.
+   */
+  status(id) {
+    v.id("refunds.status.id", id);
+    return this.req(`/api/public/refunds/${encodeURIComponent(id)}/status`, {
+      skipAuth: true
+    });
+  }
 };
 var PayoutResource = class {
   constructor(req) {
@@ -325,10 +374,15 @@ var PayoutResource = class {
   }
   list(params = {}) {
     v.optEnum("payouts.list.status", params.status, PAYOUT_STATUSES);
-    if (params.paymentIntentId !== void 0) v.id("payouts.list.paymentIntentId", params.paymentIntentId);
+    if (params.paymentIntentId !== void 0)
+      v.id("payouts.list.paymentIntentId", params.paymentIntentId);
     v.optNum("payouts.list.limit", params.limit, { min: 1, max: 100, int: true });
     return this.req(`/api/public/v1/payouts`, {
-      query: { status: params.status, payment_intent_id: params.paymentIntentId, limit: params.limit }
+      query: {
+        status: params.status,
+        payment_intent_id: params.paymentIntentId,
+        limit: params.limit
+      }
     });
   }
   replay(id) {
@@ -342,12 +396,18 @@ var WebhookEndpointResource = class {
   }
   req;
   create(input) {
-    if (!input || typeof input !== "object") throw new FragValidationError("webhookEndpoints.create", "expected object");
+    if (!input || typeof input !== "object")
+      throw new FragValidationError("webhookEndpoints.create", "expected object");
     v.url("webhookEndpoints.create.url", input.url);
     if (!Array.isArray(input.events) || input.events.length === 0) {
-      throw new FragValidationError("webhookEndpoints.create.events", "at least one event required");
+      throw new FragValidationError(
+        "webhookEndpoints.create.events",
+        "at least one event required"
+      );
     }
-    input.events.forEach((e, i) => v.enum(`webhookEndpoints.create.events[${i}]`, e, WEBHOOK_EVENTS));
+    input.events.forEach(
+      (e, i) => v.enum(`webhookEndpoints.create.events[${i}]`, e, WEBHOOK_EVENTS)
+    );
     return this.req("/api/public/v1/webhook-endpoints", {
       method: "POST",
       body: JSON.stringify(input)
@@ -364,8 +424,11 @@ var WebhookEndpointResource = class {
     v.id("webhookEndpoints.update.id", id);
     if (patch.url !== void 0) v.url("webhookEndpoints.update.url", patch.url);
     if (patch.events !== void 0) {
-      if (!Array.isArray(patch.events)) throw new FragValidationError("webhookEndpoints.update.events", "expected array");
-      patch.events.forEach((e, i) => v.enum(`webhookEndpoints.update.events[${i}]`, e, WEBHOOK_EVENTS));
+      if (!Array.isArray(patch.events))
+        throw new FragValidationError("webhookEndpoints.update.events", "expected array");
+      patch.events.forEach(
+        (e, i) => v.enum(`webhookEndpoints.update.events[${i}]`, e, WEBHOOK_EVENTS)
+      );
     }
     return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}`, {
       method: "PATCH",
@@ -374,11 +437,16 @@ var WebhookEndpointResource = class {
   }
   delete(id) {
     v.id("webhookEndpoints.delete.id", id);
-    return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}`, { method: "DELETE" });
+    return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
   }
   rotateSecret(id) {
     v.id("webhookEndpoints.rotateSecret.id", id);
-    return this.req(`/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}/rotate-secret`, { method: "POST" });
+    return this.req(
+      `/api/public/v1/webhook-endpoints/${encodeURIComponent(id)}/rotate-secret`,
+      { method: "POST" }
+    );
   }
 };
 var TokenResource = class {
@@ -408,19 +476,34 @@ var WebhookHelpers = class {
   }
 };
 async function verifyWebhook(input) {
-  if (!input || typeof input !== "object") throw new FragValidationError("verifyWebhook", "expected object");
+  if (!input || typeof input !== "object")
+    throw new FragValidationError("verifyWebhook", "expected object");
   v.str("verifyWebhook.payload", input.payload, { min: 1 });
   v.str("verifyWebhook.secret", input.secret, { min: 8 });
-  if (input.tolerance !== void 0) v.num("verifyWebhook.tolerance", input.tolerance, { min: 0, max: 3600, int: true });
+  if (input.tolerance !== void 0)
+    v.num("verifyWebhook.tolerance", input.tolerance, { min: 0, max: 3600, int: true });
   const helper = new WebhookHelpers();
-  const ok = await helper.verify(input.payload, input.signature ?? null, input.secret, input.tolerance);
-  if (!ok) throw new FragError(401, "invalid_signature", "webhook signature verification failed", null);
+  const ok = await helper.verify(
+    input.payload,
+    input.signature ?? null,
+    input.secret,
+    input.tolerance
+  );
+  if (!ok)
+    throw new FragError(401, "invalid_signature", "webhook signature verification failed", null);
   return helper.parse(input.payload);
 }
 var Frag = class extends FragmentPay {
   constructor(opts) {
     const apiKey = "secretKey" in opts ? opts.secretKey : opts.apiKey;
-    super({ apiKey, baseUrl: opts.baseUrl, fetch: opts.fetch, timeout: opts.timeout, retries: opts.retries, debug: opts.debug });
+    super({
+      apiKey,
+      baseUrl: opts.baseUrl,
+      fetch: opts.fetch,
+      timeout: opts.timeout,
+      retries: opts.retries,
+      debug: opts.debug
+    });
   }
 };
 async function hmacHex(secret, message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragmentpay/server",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "Frag server SDK — accept crypto payments from any token, on any chain, settle in one asset.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -12,19 +12,39 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
-  "keywords": ["crypto", "payments", "stablecoin", "solana", "ethereum", "usdc", "fragmentpay", "frag"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "crypto",
+    "payments",
+    "stablecoin",
+    "solana",
+    "ethereum",
+    "usdc",
+    "fragmentpay",
+    "frag"
+  ],
   "license": "MIT",
   "sideEffects": false,
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fragmentpay/fragpay.git",
     "directory": "sdk/frag-server"
   },
   "homepage": "https://github.com/fragmentpay/fragpay#readme",
-  "bugs": { "url": "https://github.com/fragmentpay/fragpay/issues" },
-  "publishConfig": { "access": "public", "provenance": true },
+  "bugs": {
+    "url": "https://github.com/fragmentpay/fragpay/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "prepublishOnly": "npm run build"