@fragmentpay/server 0.3.1 → 0.4.0

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",
@@ -79,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",
@@ -100,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;
@@ -121,20 +149,26 @@ var FragmentPay = class {
   webhookEndpoints;
   webhooks;
   tokens;
+  checkout;
   #opts;
   constructor(opts) {
     if (!opts || typeof opts !== "object") {
       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(/\/$/, ""),
+      baseUrl: (opts.baseUrl ?? "https://frag.cash").replace(/\/$/, ""),
       fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
       timeout: opts.timeout ?? 3e4,
       retries: opts.retries ?? 2,
@@ -146,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;
   }
@@ -157,7 +199,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 +263,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 +325,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,10 +349,11 @@ 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 });
+    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", {
@@ -307,12 +372,48 @@ 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.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. The returned
+   * `phase` field is a stable 4-bucket categorization
+   * (`queued | sent | completed | failed`) computed on the client for
+   * convenient status pills.
+   */
+  async status(id) {
+    v.id("refunds.status.id", id);
+    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 {
   constructor(req) {
@@ -325,10 +426,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 +448,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 +476,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 +489,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 +528,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) {
@@ -445,5 +580,6 @@ export {
   FragError,
   FragValidationError,
   FragmentPay,
+  refundPhase,
   verifyWebhook
 };