@fragmentpay/server 0.3.1 → 0.4.0

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

@@ -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;
-    created_at: string;
+    /** 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;
@@ -132,7 +191,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 +219,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;
@@ -169,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 {
@@ -201,17 +277,54 @@ 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[];
     }>;
+    /**
+     * 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. 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<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;
+        amount: string;
+        currency: string;
+        status: IntentStatus;
+        settlement_chain: string | null;
+        settlement_token: string | null;
+        expires_at: string;
+        metadata?: Record<string, unknown>;
+    }>;
 }
 declare class PayoutResource {
     private req;
@@ -283,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;
-    created_at: string;
+    /** 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;
@@ -132,7 +191,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 +219,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;
@@ -169,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 {
@@ -201,17 +277,54 @@ 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[];
     }>;
+    /**
+     * 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. 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<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;
+        amount: string;
+        currency: string;
+        status: IntentStatus;
+        settlement_chain: string | null;
+        settlement_token: string | null;
+        expires_at: string;
+        metadata?: Record<string, unknown>;
+    }>;
 }
 declare class PayoutResource {
     private req;
@@ -283,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 };