bhooai-nexus 0.1.2

package/packages/nexus-payments/src/index.ts

@@ -0,0 +1,106 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './http.js';
+export * from './signature.js';
+export * from './providers/RazorpayProvider.js';
+export * from './providers/PayPalProvider.js';
+export * from './providers/PayUProvider.js';
+export * from './providers/SkrillProvider.js';
+export * from './providers/PayoneerProvider.js';
+export * from './webhooks.js';
+
+import type { PaymentProvider, HttpTransport, ProviderConfig } from './types.js';
+import { fetchTransport } from './http.js';
+import { RazorpayProvider } from './providers/RazorpayProvider.js';
+import { PayPalProvider } from './providers/PayPalProvider.js';
+import { PayUProvider } from './providers/PayUProvider.js';
+import { SkrillProvider } from './providers/SkrillProvider.js';
+import { PayoneerProvider } from './providers/PayoneerProvider.js';
+import { WebhookRouter } from './webhooks.js';
+import type { WebhookEvent } from './types.js';
+
+export interface PaymentsOptions {
+  /** Override the HTTP transport (tests inject a mock; default uses fetch). */
+  transport?: HttpTransport;
+}
+
+export interface PaymentsService {
+  /** Enabled providers keyed by name (razorpay, paypal, payu, skrill, payoneer). */
+  providers: Map<string, PaymentProvider>;
+  /** Get a provider by name, or throw if not enabled. */
+  get(name: string): PaymentProvider;
+  /** Rebuild the enabled-provider map from (possibly updated) config in place,
+   *  so admin toggles/keys take effect without a restart. */
+  refresh(config: Parameters<typeof createPayments>[0]): void;
+  /** Build a webhook router for `POST <webhookPath>`. */
+  webhookRouter(onEvent: (event: WebhookEvent) => Promise<void> | void): WebhookRouter;
+}
+
+/**
+ * Build the payments service from a `payments` config section. A provider
+ * activates when `enabled: true` OR all of its credential keys are set — so a
+ * user who adds keys (via config or `NEXUS_PAYMENTS_*` env) without remembering
+ * the `enabled` flag still gets a working provider. Explicit `enabled: false`
+ * with keys is the only way to keep a configured provider off.
+ */
+export function createPayments(
+  config: {
+    razorpay?: ProviderConfig;
+    paypal?: ProviderConfig;
+    payu?: ProviderConfig;
+    skrill?: ProviderConfig;
+    payoneer?: ProviderConfig;
+  },
+  opts: PaymentsOptions = {},
+): PaymentsService {
+  const transport = opts.transport ?? fetchTransport;
+  const providers = new Map<string, PaymentProvider>();
+
+  const active = (cfg: ProviderConfig | undefined, keys: string[]): boolean => {
+    if (!cfg) return false;
+    const hasKeys = keys.every((k) => {
+      const v = (cfg as Record<string, unknown>)[k];
+      return typeof v === 'string' && v.length > 0;
+    });
+    if (!hasKeys) return false; // never instantiate without the required keys
+    // Keys present → provider works (matches "add keys and it activates"),
+    // unless explicitly disabled.
+    return cfg.enabled !== false;
+  };
+
+  const populate = (cfg: Parameters<typeof createPayments>[0]): void => {
+    providers.clear();
+    if (active(cfg.razorpay, ['keyId', 'keySecret'])) {
+      providers.set('razorpay', new RazorpayProvider(cfg.razorpay as any, transport));
+    }
+    if (active(cfg.paypal, ['clientId', 'clientSecret'])) {
+      providers.set('paypal', new PayPalProvider(cfg.paypal as any, transport));
+    }
+    if (active(cfg.payu, ['merchantKey', 'salt'])) {
+      providers.set('payu', new PayUProvider(cfg.payu as any, transport));
+    }
+    if (active(cfg.skrill, ['merchantEmail'])) {
+      providers.set('skrill', new SkrillProvider(cfg.skrill as any, transport));
+    }
+    if (active(cfg.payoneer, ['programId', 'apiKey'])) {
+      providers.set('payoneer', new PayoneerProvider(cfg.payoneer as any, transport));
+    }
+  };
+
+  populate(config);
+
+  return {
+    providers,
+    get(name: string): PaymentProvider {
+      const p = providers.get(name);
+      if (!p) throw new Error(`[nexus-payments] provider not enabled: ${name}`);
+      return p;
+    },
+    refresh(cfg) {
+      populate(cfg);
+    },
+    webhookRouter(onEvent) {
+      return new WebhookRouter(providers, onEvent);
+    },
+  };
+}

package/packages/nexus-payments/src/providers/PayPalProvider.ts

@@ -0,0 +1,192 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+  ConnectionTest,
+} from '../types.js';
+import { jsonRequest, basicAuth } from '../http.js';
+import { PaymentError } from '../errors.js';
+
+interface PayPalConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  clientId: string;
+  clientSecret: string;
+  /** Optional webhook id (used by the verify-webhook-signature API). */
+  webhookId?: string;
+}
+
+function baseUrl(sandbox: boolean): string {
+  return sandbox ? 'https://api-m.sandbox.paypal.com' : 'https://api-m.paypal.com';
+}
+
+function mapStatus(s: string): OrderStatus {
+  switch (s) {
+    case 'CREATED': return 'created';
+    case 'SAVED': case 'PAYER_ACTION_REQUIRED': return 'pending';
+    case 'APPROVED': return 'authorized';
+    case 'COMPLETED': return 'captured';
+    case 'VOIDED': return 'cancelled';
+    default: return 'pending';
+  }
+}
+
+/** Format a major-unit amount as PayPal's 2-decimal string. */
+function fmt(amount: number): string {
+  return amount.toFixed(2);
+}
+
+export class PayPalProvider implements PaymentProvider {
+  readonly name = 'paypal';
+  private readonly cfg: PayPalConfig;
+  private readonly transport: HttpTransport;
+  private token: { value: string; expiresAt: number } | null = null;
+
+  constructor(cfg: PayPalConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.clientId || !cfg.clientSecret) throw new PaymentError('paypal clientId/clientSecret required', { code: 'CONFIG', provider: 'paypal' });
+  }
+
+  private base(): string {
+    return baseUrl(this.cfg.sandbox);
+  }
+
+  /** OAuth2 client-credentials token with a 5-minute safety margin on expiry. */
+  private async tokenValue(): Promise<string> {
+    if (this.token && Date.now() < this.token.expiresAt - 300_000) return this.token.value;
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v1/oauth2/token`,
+      headers: { authorization: basicAuth(this.cfg.clientId, this.cfg.clientSecret), 'content-type': 'application/x-www-form-urlencoded' },
+      body: 'grant_type=client_credentials',
+    });
+    if (!res.access_token) throw new PaymentError('paypal token exchange failed', { code: 'AUTH', provider: 'paypal', raw: res });
+    this.token = { value: res.access_token, expiresAt: Date.now() + (res.expires_in ?? 3600) * 1000 };
+    return this.token.value;
+  }
+
+  private async authHeaders(): Promise<Record<string, string>> {
+    return { 'content-type': 'application/json', authorization: `Bearer ${await this.tokenValue()}` };
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const body = {
+      intent: 'CAPTURE',
+      purchase_units: [{
+        reference_id: input.reference,
+        amount: { currency_code: input.currency, value: fmt(input.amount) },
+        ...(input.description ? { description: input.description } : {}),
+      }],
+      ...(input.returnUrl || input.cancelUrl ? { application_context: { return_url: input.returnUrl, cancel_url: input.cancelUrl } } : {}),
+    };
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v2/checkout/orders`,
+      headers: await this.authHeaders(),
+      body: JSON.stringify(body),
+    });
+    const approve = (res.links ?? []).find((l: { rel: string; href: string }) => l.rel === 'approve');
+    return {
+      id: res.id,
+      reference: input.reference,
+      status: mapStatus(res.status),
+      amount: input.amount,
+      currency: input.currency,
+      paymentUrl: approve?.href,
+      raw: res,
+    };
+  }
+
+  async capture(input: CaptureInput): Promise<Order> {
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v2/checkout/orders/${input.orderId}/capture`,
+      headers: await this.authHeaders(),
+      body: '{}',
+    });
+    const unit = res.purchase_units?.[0];
+    const capture = unit?.payments?.captures?.[0];
+    return {
+      id: res.id,
+      reference: unit?.reference_id ?? '',
+      status: mapStatus(res.status),
+      amount: capture ? Number(capture.amount.value) : 0,
+      currency: capture?.amount?.currency_code ?? '',
+      paymentId: capture?.id,
+      raw: res,
+    };
+  }
+
+  async refund(input: RefundInput): Promise<RefundResult> {
+    const body = input.amount != null ? JSON.stringify({ amount: { value: fmt(input.amount), currency_code: 'USD' } }) : '{}';
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v2/payments/captures/${input.paymentId}/refund`,
+      headers: await this.authHeaders(),
+      body,
+    });
+    return { id: res.id, status: res.status, amount: res.amount ? Number(res.amount.value) : 0, raw: res };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'GET',
+      url: `${this.base()}/v2/checkout/orders/${orderId}`,
+      headers: await this.authHeaders(),
+    });
+    const unit = res.purchase_units?.[0];
+    return {
+      id: res.id,
+      reference: unit?.reference_id ?? '',
+      status: mapStatus(res.status),
+      amount: unit ? Number(unit.amount.value) : 0,
+      currency: unit?.amount?.currency_code ?? '',
+      raw: res,
+    };
+  }
+
+  /** Live probe: exchange client-credentials for an OAuth token (no order created). */
+  async testConnection(): Promise<ConnectionTest> {
+    await this.tokenValue();
+    return { ok: true, detail: `oauth2 authenticated (${this.cfg.sandbox ? 'sandbox' : 'live'})` };
+  }
+
+  /**
+   * PayPal webhook verification uses the /v1/notifications/verify-webhook-signature
+   * API (PayPal signs with a rotating certificate — local HMAC isn't possible).
+   * Requires `webhookId` configured.
+   */
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    if (!this.cfg.webhookId) return { verified: false, provider: this.name, data: 'no webhookId configured' };
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const body = JSON.stringify({
+      auth_algo: input.headers['paypal-auth-algo'] ?? input.headers['PAYPAL-AUTH-ALGO'],
+      cert_url: input.headers['paypal-cert-url'] ?? input.headers['PAYPAL-CERT-URL'],
+      transmission_id: input.headers['paypal-transmission-id'] ?? input.headers['PAYPAL-TRANSMISSION-ID'],
+      transmission_sig: input.headers['paypal-transmission-sig'] ?? input.headers['PAYPAL-TRANSMISSION-SIG'],
+      transmission_time: input.headers['paypal-transmission-time'] ?? input.headers['PAYPAL-TRANSMISSION-TIME'],
+      webhook_id: this.cfg.webhookId,
+      webhook_event: safeParse(raw),
+    });
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v1/notifications/verify-webhook-signature`,
+      headers: await this.authHeaders(),
+      body,
+    });
+    const verified = res.verification_status === 'SUCCESS';
+    return { verified, event: safeParse(raw)?.event_type, data: safeParse(raw), provider: this.name };
+  }
+}
+
+function safeParse(s: string): any {
+  try { return JSON.parse(s); } catch { return undefined; }
+}

package/packages/nexus-payments/src/providers/PayUProvider.ts

@@ -0,0 +1,164 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+} from '../types.js';
+import { sha512Hex, safeEqual } from '../signature.js';
+import { PaymentError } from '../errors.js';
+
+/**
+ * PayU India (happy-path). PayU uses a hash-based flow: the merchant computes a
+ * SHA-512 hash over the payment params + salt, POSTs to the hosted checkout, and
+ * verifies the response hash (the reverse sequence). No REST "create order";
+ * `createOrder` builds the params + hash and returns the checkout URL.
+ */
+interface PayUConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  merchantKey: string;
+  salt: string;
+}
+
+function checkoutUrl(sandbox: boolean): string {
+  return sandbox ? 'https://test.payu.in/_payment' : 'https://secure.payu.in/_payment';
+}
+
+/** Request hash = sha512(key|txnid|amount|productinfo|firstname|email|udf1..udf10|salt). */
+export function payuRequestHash(
+  key: string,
+  salt: string,
+  p: { txnid: string; amount: string; productinfo: string; firstname: string; email: string; udf: string[] },
+): string {
+  const fields = [key, p.txnid, p.amount, p.productinfo, p.firstname, p.email, ...p.udf, salt];
+  return sha512Hex(fields.join('|'));
+}
+
+/** Response hash = sha512(salt|status|udf10..udf1|email|firstname|productinfo|amount|txnid|key). */
+export function payuResponseHash(
+  key: string,
+  salt: string,
+  p: { status: string; txnid: string; amount: string; productinfo: string; firstname: string; email: string; udf: string[] },
+): string {
+  const reversedUdf = [...p.udf].reverse();
+  const fields = [salt, p.status, ...reversedUdf, p.email, p.firstname, p.productinfo, p.amount, p.txnid, key];
+  return sha512Hex(fields.join('|'));
+}
+
+function mapStatus(status: string): OrderStatus {
+  switch (status) {
+    case 'created': return 'created';
+    case 'pending': case 'in progress': return 'pending';
+    case 'captured': case 'success': return 'captured';
+    case 'failed': return 'failed';
+    case 'cancelled': return 'cancelled';
+    case 'refunded': return 'refunded';
+    default: return 'pending';
+  }
+}
+
+export class PayUProvider implements PaymentProvider {
+  readonly name = 'payu';
+  private readonly cfg: PayUConfig;
+  private readonly transport: HttpTransport;
+
+  constructor(cfg: PayUConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.merchantKey || !cfg.salt) throw new PaymentError('payu merchantKey/salt required', { code: 'CONFIG', provider: 'payu' });
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const amount = input.amount.toFixed(2);
+    const firstname = input.customer?.name ?? 'Customer';
+    const email = input.customer?.email ?? '';
+    const productinfo = input.description ?? input.reference;
+    const udf = ['', '', '', '', '', '', '', '', '', '']; // udf1..udf10
+    const hash = payuRequestHash(this.cfg.merchantKey, this.cfg.salt, {
+      txnid: input.reference, amount, productinfo, firstname, email, udf,
+    });
+    const params = {
+      key: this.cfg.merchantKey,
+      txnid: input.reference,
+      amount,
+      productinfo,
+      firstname,
+      email,
+      udf1: '', udf2: '', udf3: '', udf4: '', udf5: '',
+      hash,
+      ...(input.returnUrl ? { surl: input.returnUrl, furl: input.returnUrl } : {}),
+    };
+    return {
+      id: input.reference,
+      reference: input.reference,
+      status: 'created',
+      amount: input.amount,
+      currency: input.currency,
+      // PayU expects a form POST to the checkout URL with `params` — return the
+      // endpoint as paymentUrl and the params in `raw` for the client to POST.
+      paymentUrl: checkoutUrl(this.cfg.sandbox),
+      raw: params,
+    };
+  }
+
+  /** PayU has no server-side capture; payments auto-capture on the hosted page. */
+  async capture(input: CaptureInput): Promise<Order> {
+    return this.getOrderStatus(input.orderId);
+  }
+
+  /** PayU refunds require the merchant panel / a separate API; v1 returns a stub. */
+  async refund(input: RefundInput): Promise<RefundResult> {
+    return { id: `refund-${input.paymentId}`, status: 'pending', amount: input.amount ?? 0, raw: { note: 'PayU refund via merchant panel (v1)' } };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    // Without a live REST credential, status is reconstructed from the webhook
+    // payload that updateOrder would have stored. v1 returns a placeholder.
+    return { id: orderId, reference: orderId, status: 'pending', amount: 0, currency: '', raw: { note: 'PayU status via webhook (v1)' } };
+  }
+
+  /**
+   * Verify a PayU webhook/redirect response. The body is form-encoded
+   * (key=value&...) with a `hash` field. We recompute the response hash and
+   * compare in constant time.
+   */
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const fields = parseForm(raw);
+    const providedHash = fields.hash;
+    if (!providedHash) return { verified: false, provider: this.name, data: 'no hash in payload' };
+    const udf = [fields.udf1, fields.udf2, fields.udf3, fields.udf4, fields.udf5, fields.udf6, fields.udf7, fields.udf8, fields.udf9, fields.udf10].map((v) => v ?? '');
+    const expected = payuResponseHash(this.cfg.merchantKey, this.cfg.salt, {
+      status: fields.status ?? '',
+      txnid: fields.txnid ?? '',
+      amount: fields.amount ?? '',
+      productinfo: fields.productinfo ?? '',
+      firstname: fields.firstname ?? '',
+      email: fields.email ?? '',
+      udf,
+    });
+    const verified = safeEqual(providedHash, expected);
+    return {
+      verified,
+      event: fields.status ? `payment.${fields.status}` : undefined,
+      data: fields,
+      provider: this.name,
+    };
+  }
+}
+
+function parseForm(body: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const pair of body.split('&')) {
+    if (!pair) continue;
+    const [k, ...rest] = pair.split('=');
+    out[decodeURIComponent(k!)] = decodeURIComponent(rest.join('='));
+  }
+  return out;
+}

package/packages/nexus-payments/src/providers/PayoneerProvider.ts

@@ -0,0 +1,122 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+} from '../types.js';
+import { hmacSha256Hex, safeEqual } from '../signature.js';
+import { PaymentError } from '../errors.js';
+
+/**
+ * Payoneer (happy-path). Payoneer's API requires a registered partner program
+ * and has no public sandbox without provisioned credentials, so this adapter is
+ * structurally complete but verified by signature tests rather than live calls.
+ *
+ * The flow modeled here: the merchant builds a signed payment request (HMAC over
+ * the canonical params) and redirects to a Payoneer checkout URL; Payoneer posts
+ * a webhook signed with the same shared secret (HMAC-SHA256 over the raw body).
+ */
+interface PayoneerConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  programId: string;
+  apiKey: string;
+  /** Shared secret for webhook HMAC verification. */
+  webhookSecret?: string;
+}
+
+function checkoutUrl(sandbox: boolean, programId: string): string {
+  return sandbox
+    ? `https://api.sandbox.payoneer.com/checkout/${programId}`
+    : `https://api.payoneer.com/checkout/${programId}`;
+}
+
+function mapStatus(status: string): OrderStatus {
+  switch (status) {
+    case 'initiated': return 'created';
+    case 'pending': return 'pending';
+    case 'authorized': return 'authorized';
+    case 'completed': case 'paid': return 'captured';
+    case 'failed': return 'failed';
+    case 'cancelled': return 'cancelled';
+    case 'refunded': return 'refunded';
+    default: return 'pending';
+  }
+}
+
+export class PayoneerProvider implements PaymentProvider {
+  readonly name = 'payoneer';
+  private readonly cfg: PayoneerConfig;
+  private readonly transport: HttpTransport;
+
+  constructor(cfg: PayoneerConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.programId || !cfg.apiKey) throw new PaymentError('payoneer programId/apiKey required', { code: 'CONFIG', provider: 'payoneer' });
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const params = new URLSearchParams();
+    params.set('program_id', this.cfg.programId);
+    params.set('reference', input.reference);
+    params.set('amount', input.amount.toFixed(2));
+    params.set('currency', input.currency);
+    if (input.customer?.email) params.set('payee_email', input.customer.email);
+    if (input.returnUrl) params.set('return_url', input.returnUrl);
+    // Canonical signature: HMAC-SHA256(apiKey, sorted query string).
+    const canonical = canonicalQuery(params);
+    const signature = hmacSha256Hex(this.cfg.apiKey, canonical);
+    params.set('signature', signature);
+    return {
+      id: input.reference,
+      reference: input.reference,
+      status: 'created',
+      amount: input.amount,
+      currency: input.currency,
+      paymentUrl: `${checkoutUrl(this.cfg.sandbox, this.cfg.programId)}?${params.toString()}`,
+      raw: Object.fromEntries(params),
+    };
+  }
+
+  async capture(input: CaptureInput): Promise<Order> {
+    return this.getOrderStatus(input.orderId);
+  }
+
+  async refund(_input: RefundInput): Promise<RefundResult> {
+    return { id: `payoneer-refund`, status: 'pending', amount: 0, raw: { note: 'Payoneer refund via partner API (v1)' } };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    return { id: orderId, reference: orderId, status: 'pending', amount: 0, currency: '', raw: { note: 'Payoneer status via webhook (v1)' } };
+  }
+
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    const secret = this.cfg.webhookSecret;
+    if (!secret) return { verified: false, provider: this.name, data: 'no webhookSecret configured' };
+    const sig = input.headers['x-payoneer-signature'] ?? input.headers['X-Payoneer-Signature'];
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const expected = hmacSha256Hex(secret, raw);
+    const verified = typeof sig === 'string' && safeEqual(sig, expected);
+    let event: string | undefined;
+    let data: unknown;
+    try {
+      const parsed = JSON.parse(raw);
+      event = parsed.event ?? parsed.status;
+      data = parsed;
+    } catch {
+      data = raw;
+    }
+    return { verified, event, data, provider: this.name };
+  }
+}
+
+/** Sort params by key and encode as `k=v&k=v` (deterministic for signing). */
+function canonicalQuery(params: URLSearchParams): string {
+  return [...params.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([k, v]) => `${k}=${v}`).join('&');
+}