softycomp-node 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kobie Wentzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,418 @@
+# softycomp-node
+
+[![npm version](https://img.shields.io/npm/v/softycomp-node.svg)](https://www.npmjs.com/package/softycomp-node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+
+**Official Node.js SDK for SoftyComp** — South African bill presentment and debit order platform.
+
+Accept once-off and recurring payments via card, EFT, and debit order with a simple, type-safe API.
+
+## Features
+
+- **Bill Presentment** — Create payment links for once-off or recurring bills
+- **Debit Orders** — Monthly and yearly recurring collections
+- **Refunds** — Process full or partial refunds via credit transactions
+- **Webhooks** — Real-time payment notifications with signature validation
+- **TypeScript** — Fully typed for autocomplete and type safety
+- **Zero Dependencies** — Uses native `fetch()` (Node.js 18+)
+- **Sandbox Support** — Test with sandbox environment before going live
+
+## Installation
+
+```bash
+npm install softycomp-node
+```
+
+**Requirements:** Node.js 18+ (for native `fetch()` support)
+
+## Quick Start
+
+```typescript
+import { SoftyComp } from 'softycomp-node';
+
+// Initialize client
+const client = new SoftyComp({
+  apiKey: 'your-api-key',
+  secretKey: 'your-secret-key',
+  sandbox: true, // Use test environment
+});
+
+// Create a once-off bill
+const bill = await client.createBill({
+  amount: 299.00, // In Rands (not cents!)
+  customerName: 'John Doe',
+  customerEmail: 'john@example.com',
+  customerPhone: '0825551234',
+  reference: 'INV-001',
+  description: 'Product purchase',
+  frequency: 'once-off',
+  returnUrl: 'https://myapp.com/payment/success',
+  cancelUrl: 'https://myapp.com/payment/cancel',
+  notifyUrl: 'https://myapp.com/payment/webhook',
+});
+
+// Redirect customer to payment page
+console.log(bill.paymentUrl);
+```
+
+## API Reference
+
+### Initialize Client
+
+```typescript
+const client = new SoftyComp({
+  apiKey: string;          // Your SoftyComp API key
+  secretKey: string;       // Your SoftyComp API secret
+  sandbox?: boolean;       // Use sandbox environment (default: true)
+  webhookSecret?: string;  // Optional secret for webhook signature validation
+});
+```
+
+**Environments:**
+- **Sandbox:** `sandbox.softycomp.co.za`
+- **Production:** `api.softycomp.co.za`
+
+### Create Bill
+
+Create a payment bill (once-off or recurring).
+
+```typescript
+const bill = await client.createBill({
+  amount: number;              // Amount in Rands (not cents!) e.g. 299.00
+  customerName: string;        // Customer full name
+  customerEmail: string;       // Customer email
+  customerPhone: string;       // Customer mobile (e.g. "0825551234")
+  reference: string;           // Your internal reference/invoice number
+  description?: string;        // Bill description
+  frequency: 'once-off' | 'monthly' | 'yearly';
+
+  // Recurring bill fields (ignored for once-off):
+  commencementDate?: string;   // Start date (YYYY-MM-DD). Must be future (min tomorrow)
+  recurringDay?: number;       // Day of month to charge (1-28). Defaults to tomorrow
+  recurringMonth?: number;     // Month for yearly bills (1-12). Defaults to tomorrow
+
+  // URLs:
+  returnUrl: string;           // Success redirect URL
+  cancelUrl: string;           // Cancel redirect URL
+  notifyUrl: string;           // Webhook notification URL
+
+  // Optional branding:
+  companyName?: string;        // Company name to display
+  companyContact?: string;     // Company contact number
+  companyEmail?: string;       // Company email
+});
+
+// Returns:
+{
+  reference: string;     // SoftyComp bill reference
+  paymentUrl: string;    // URL to redirect customer to
+  expiresAt: string;     // ISO 8601 expiry timestamp (typically 30 mins)
+}
+```
+
+#### Examples
+
+**Once-off payment:**
+
+```typescript
+const bill = await client.createBill({
+  amount: 150.00,
+  customerName: 'Jane Smith',
+  customerEmail: 'jane@example.com',
+  customerPhone: '0821234567',
+  reference: 'ORDER-789',
+  frequency: 'once-off',
+  returnUrl: 'https://myapp.com/success',
+  cancelUrl: 'https://myapp.com/cancel',
+  notifyUrl: 'https://myapp.com/webhook',
+});
+```
+
+**Monthly subscription:**
+
+```typescript
+const bill = await client.createBill({
+  amount: 99.00,
+  customerName: 'John Doe',
+  customerEmail: 'john@example.com',
+  customerPhone: '0825551234',
+  reference: 'SUB-001',
+  description: 'Premium Monthly Subscription',
+  frequency: 'monthly',
+  commencementDate: '2026-04-01',  // First charge date
+  recurringDay: 1,                  // Charge on 1st of each month
+  returnUrl: 'https://myapp.com/success',
+  cancelUrl: 'https://myapp.com/cancel',
+  notifyUrl: 'https://myapp.com/webhook',
+});
+```
+
+**Yearly subscription:**
+
+```typescript
+const bill = await client.createBill({
+  amount: 999.00,
+  customerName: 'Alice Johnson',
+  customerEmail: 'alice@example.com',
+  customerPhone: '0827778888',
+  reference: 'SUB-ANNUAL-042',
+  description: 'Annual Premium Plan',
+  frequency: 'yearly',
+  commencementDate: '2027-01-15',
+  recurringDay: 15,
+  recurringMonth: 1,  // Charge on January 15th each year
+  returnUrl: 'https://myapp.com/success',
+  cancelUrl: 'https://myapp.com/cancel',
+  notifyUrl: 'https://myapp.com/webhook',
+});
+```
+
+### Get Bill Status
+
+Check payment status of a bill.
+
+```typescript
+const status = await client.getBillStatus('BILL-REF-123');
+
+// Returns:
+{
+  reference: string;       // Bill reference
+  status: 'pending' | 'completed' | 'failed' | 'cancelled';
+  amount: number;          // Amount in Rands
+  paidAt?: string;         // ISO 8601 payment timestamp (if paid)
+  data: any;               // Raw response from SoftyComp
+}
+```
+
+### Refund Payment
+
+Process a full or partial refund (credit transaction).
+
+```typescript
+// Full refund
+const refund = await client.refund({
+  transactionId: 'TXN-123',
+});
+
+// Partial refund
+const refund = await client.refund({
+  transactionId: 'TXN-123',
+  amount: 50.00,  // Amount in Rands
+});
+
+// Returns:
+{
+  refundId: string;        // Refund reference
+  status: 'completed' | 'pending' | 'failed';
+  amount: number;          // Amount refunded in Rands
+}
+```
+
+### Webhook Handling
+
+SoftyComp sends real-time payment notifications to your `notifyUrl`.
+
+#### Verify Webhook Signature
+
+```typescript
+import express from 'express';
+
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-signature'] as string;
+
+  if (!client.verifyWebhook(req.body, { signature })) {
+    return res.status(400).send('Invalid signature');
+  }
+
+  // Signature valid, process webhook...
+  res.status(200).send('OK');
+});
+```
+
+#### Parse Webhook Event
+
+```typescript
+const event = client.parseWebhook(req.body);
+
+// Returns:
+{
+  type: 'pending' | 'successful' | 'failed' | 'cancelled';
+  reference: string;           // Transaction reference
+  status: 'pending' | 'completed' | 'failed' | 'cancelled';
+  amount: number;              // Amount in Rands
+  transactionDate: string;     // ISO 8601 timestamp
+  paymentMethodId: number;     // Payment method ID (1=Card, 2=EFT, etc.)
+  paymentMethod: string;       // Payment method description
+  userReference: string;       // Your original reference
+  information: string;         // Additional info
+  raw: any;                    // Raw webhook payload
+}
+```
+
+#### Full Webhook Example
+
+```typescript
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  // 1. Verify signature (optional but recommended)
+  const signature = req.headers['x-signature'] as string;
+  if (!client.verifyWebhook(req.body, { signature })) {
+    return res.status(400).send('Invalid signature');
+  }
+
+  // 2. Parse webhook event
+  const event = client.parseWebhook(req.body);
+
+  // 3. Handle event types
+  switch (event.type) {
+    case 'successful':
+      console.log('Payment successful!');
+      console.log(`Reference: ${event.reference}`);
+      console.log(`Amount: R${event.amount}`);
+      console.log(`Method: ${event.paymentMethod}`);
+      // Update your database, send confirmation email, etc.
+      break;
+
+    case 'failed':
+      console.log('Payment failed:', event.reference);
+      // Notify customer, retry payment, etc.
+      break;
+
+    case 'cancelled':
+      console.log('Payment cancelled:', event.reference);
+      // Handle cancellation
+      break;
+
+    case 'pending':
+      console.log('Payment pending:', event.reference);
+      // Wait for final status
+      break;
+  }
+
+  // 4. Respond with 200 OK
+  res.status(200).send('OK');
+});
+```
+
+## Test Cards
+
+Use these test cards in the **sandbox environment** only:
+
+| Card Number | 3DS | MOTO | Description |
+|-------------|-----|------|-------------|
+| `4790 4444 4444 4444` | ✅ Success | ✅ Success | Both 3DS and MOTO succeed |
+| `4790 3333 3333 3333` | ✅ Success | ❌ Fail | 3DS succeeds, MOTO fails |
+
+**CVV:** Any 3 digits
+**Expiry:** Any future date
+
+## Important Notes
+
+### Amounts in Rands (Not Cents!)
+
+Unlike most payment SDKs, SoftyComp uses **Rands**, not cents:
+
+```typescript
+// ✅ Correct
+amount: 299.00  // R299.00
+
+// ❌ Wrong
+amount: 29900   // Would be R29,900.00!
+```
+
+### Recurring Bill Requirements
+
+For `frequency: 'monthly'` or `'yearly'`:
+
+1. **Commencement Date** must be a future date (minimum tomorrow)
+2. **Recurring Day** should be 1-28 (avoids month-end issues)
+3. **Recurring Month** only for yearly bills (1=Jan, 12=Dec)
+
+```typescript
+// ✅ Correct
+commencementDate: '2026-04-01',  // Future date
+recurringDay: 15,                // 15th of each month
+
+// ❌ Wrong
+commencementDate: '2026-03-20',  // Past date
+recurringDay: 31,                // Doesn't exist in all months
+```
+
+### Frequency Codes (Internal)
+
+The SDK handles this automatically, but for reference:
+
+- `1` = Once-off
+- `2` = Monthly
+- `7` = Yearly
+
+### Webhook Activity Types (Internal)
+
+The SDK maps these to friendly event types:
+
+- `1` = Pending → `type: 'pending'`
+- `2` = Successful → `type: 'successful'`
+- `3` = Failed → `type: 'failed'`
+- `4` = Cancelled → `type: 'cancelled'`
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import {
+  SoftyComp,
+  BillFrequency,
+  PaymentStatus,
+  WebhookEvent,
+  CreateBillParams,
+  RefundParams
+} from 'softycomp-node';
+```
+
+## Error Handling
+
+All methods throw descriptive errors:
+
+```typescript
+try {
+  const bill = await client.createBill({
+    // ... params
+  });
+} catch (error) {
+  console.error('Failed to create bill:', error.message);
+  // "Failed to create bill: SoftyComp API error (POST /api/paygatecontroller/requestbillpresentment): 400 - Invalid email address"
+}
+```
+
+Common errors:
+- Authentication: `SoftyComp authentication failed: 401 - Unauthorized`
+- Invalid date: `commencementDate must be a future date (minimum tomorrow)`
+- API errors: `SoftyComp API error (POST /path): 400 - Error message`
+
+## Production Checklist
+
+Before going live:
+
+1. **Get production credentials** from SoftyComp
+2. **Set `sandbox: false`** in config
+3. **Configure webhook secret** for signature validation
+4. **Test webhook endpoint** with production credentials
+5. **Handle all webhook event types** (pending, successful, failed, cancelled)
+6. **Implement idempotency** to avoid duplicate processing
+7. **Log all transactions** for debugging and reconciliation
+8. **Set up monitoring** for failed webhooks
+
+## License
+
+MIT © Kobie Wentzel
+
+## Links
+
+- **GitHub:** [kobie3717/softycomp-node](https://github.com/kobie3717/softycomp-node)
+- **SoftyComp:** [softycompdistribution.co.za](https://softycompdistribution.co.za)
+- **API Docs:** [webapps.softycomp.co.za](https://webapps.softycomp.co.za)
+
+---
+
+**Built by [Kobie Wentzel](https://github.com/kobie3717)** for the South African developer community.

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+/**
+ * SoftyComp Node.js SDK
+ *
+ * Official Node.js SDK for SoftyComp — South African bill presentment and debit order platform.
+ *
+ * @see https://softycompdistribution.co.za
+ * @see https://webapps.softycomp.co.za (API documentation)
+ */
+export type BillFrequency = 'once-off' | 'monthly' | 'yearly';
+export type PaymentStatus = 'pending' | 'completed' | 'failed' | 'cancelled';
+export type WebhookType = 'pending' | 'successful' | 'failed' | 'cancelled';
+export interface SoftyCompConfig {
+    /** Your SoftyComp API key */
+    apiKey: string;
+    /** Your SoftyComp API secret */
+    secretKey: string;
+    /** Use sandbox environment (testapi.softycompdistribution.co.za) */
+    sandbox?: boolean;
+    /** Optional webhook secret for signature validation */
+    webhookSecret?: string;
+}
+export interface CreateBillParams {
+    /** Amount in Rands (not cents!) e.g. 299.00 */
+    amount: number;
+    /** Customer full name */
+    customerName: string;
+    /** Customer email address */
+    customerEmail: string;
+    /** Customer mobile number (e.g. "0825551234") */
+    customerPhone: string;
+    /** Your internal reference/invoice number */
+    reference: string;
+    /** Bill description */
+    description?: string;
+    /** Payment frequency: 'once-off', 'monthly', or 'yearly' */
+    frequency: BillFrequency;
+    /** Commencement date for recurring bills (YYYY-MM-DD). Must be future date (min tomorrow). Ignored for once-off. */
+    commencementDate?: string;
+    /** Day of month to charge for recurring bills (1-28). Ignored for once-off. Defaults to tomorrow's day. */
+    recurringDay?: number;
+    /** Month to charge for yearly bills (1-12). Ignored for monthly/once-off. Defaults to tomorrow's month. */
+    recurringMonth?: number;
+    /** URL to redirect customer after successful payment */
+    returnUrl: string;
+    /** URL to redirect customer after cancelled payment */
+    cancelUrl: string;
+    /** URL to receive webhook notifications */
+    notifyUrl: string;
+    /** Company name to display on bill */
+    companyName?: string;
+    /** Company contact number to display */
+    companyContact?: string;
+    /** Company email to display */
+    companyEmail?: string;
+}
+export interface CreateBillResult {
+    /** Unique bill reference from SoftyComp */
+    reference: string;
+    /** Payment URL to redirect customer to */
+    paymentUrl: string;
+    /** ISO 8601 timestamp when the payment link expires (typically 30 minutes) */
+    expiresAt: string;
+}
+export interface RefundParams {
+    /** Original transaction ID/reference to refund */
+    transactionId: string;
+    /** Amount to refund in Rands (not cents!). Omit for full refund. */
+    amount?: number;
+}
+export interface RefundResult {
+    /** Refund reference ID */
+    refundId: string;
+    /** Refund status */
+    status: 'completed' | 'pending' | 'failed';
+    /** Amount refunded in Rands */
+    amount: number;
+}
+export interface WebhookEvent {
+    /** Event type: 'pending', 'successful', 'failed', 'cancelled' */
+    type: WebhookType;
+    /** Transaction reference */
+    reference: string;
+    /** Payment status */
+    status: PaymentStatus;
+    /** Amount in Rands */
+    amount: number;
+    /** Transaction date (ISO 8601) */
+    transactionDate: string;
+    /** Payment method ID (1=Card, 2=EFT, etc.) */
+    paymentMethodId: number;
+    /** Payment method description */
+    paymentMethod: string;
+    /** Your original reference */
+    userReference: string;
+    /** Additional information */
+    information: string;
+    /** Raw webhook payload */
+    raw: any;
+}
+export interface BillStatusResult {
+    /** Bill reference */
+    reference: string;
+    /** Current payment status */
+    status: PaymentStatus;
+    /** Amount in Rands */
+    amount: number;
+    /** Transaction date if paid */
+    paidAt?: string;
+    /** Raw response data */
+    data: any;
+}
+export declare class SoftyComp {
+    private apiKey;
+    private secretKey;
+    private sandbox;
+    private baseUrl;
+    private webhookSecret?;
+    private token;
+    private tokenExpiry;
+    constructor(config: SoftyCompConfig);
+    /**
+     * Authenticate and get Bearer token (cached for ~30 minutes)
+     * @internal
+     */
+    private authenticate;
+    /**
+     * Make authenticated API request
+     * @internal
+     */
+    private apiRequest;
+    /**
+     * Create a payment bill (once-off or recurring)
+     *
+     * @example
+     * ```typescript
+     * const bill = await client.createBill({
+     *   amount: 299.00,
+     *   customerName: 'John Doe',
+     *   customerEmail: 'john@example.com',
+     *   customerPhone: '0825551234',
+     *   reference: 'INV-001',
+     *   description: 'Monthly subscription',
+     *   frequency: 'monthly',
+     *   commencementDate: '2026-04-01',
+     *   recurringDay: 1,
+     *   returnUrl: 'https://myapp.com/success',
+     *   cancelUrl: 'https://myapp.com/cancel',
+     *   notifyUrl: 'https://myapp.com/webhook'
+     * });
+     *
+     * // Redirect customer to payment page
+     * console.log(bill.paymentUrl);
+     * ```
+     */
+    createBill(params: CreateBillParams): Promise<CreateBillResult>;
+    /**
+     * Get bill payment status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.getBillStatus('BILL-REF-123');
+     * if (status.status === 'completed') {
+     *   console.log('Payment received on:', status.paidAt);
+     * }
+     * ```
+     */
+    getBillStatus(reference: string): Promise<BillStatusResult>;
+    /**
+     * Process a refund (credit transaction)
+     *
+     * @example
+     * ```typescript
+     * // Full refund
+     * const refund = await client.refund({ transactionId: 'TXN-123' });
+     *
+     * // Partial refund
+     * const refund = await client.refund({
+     *   transactionId: 'TXN-123',
+     *   amount: 100.00
+     * });
+     * ```
+     */
+    refund(params: RefundParams): Promise<RefundResult>;
+    /**
+     * Verify webhook signature (HMAC-SHA256)
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const signature = req.headers['x-signature'] as string;
+     *   if (!client.verifyWebhook(req.body, { signature })) {
+     *     return res.status(400).send('Invalid signature');
+     *   }
+     *   // Process webhook...
+     * });
+     * ```
+     */
+    verifyWebhook(body: string | Buffer, headers: {
+        signature?: string;
+    } | Record<string, string>): boolean;
+    /**
+     * Parse webhook event payload
+     *
+     * @example
+     * ```typescript
+     * const event = client.parseWebhook(req.body);
+     *
+     * switch (event.type) {
+     *   case 'successful':
+     *     console.log('Payment successful:', event.reference, event.amount);
+     *     break;
+     *   case 'failed':
+     *     console.log('Payment failed:', event.reference);
+     *     break;
+     *   case 'cancelled':
+     *     console.log('Payment cancelled:', event.reference);
+     *     break;
+     * }
+     * ```
+     */
+    parseWebhook(body: any): WebhookEvent;
+    /**
+     * Map SoftyComp status type ID to payment status
+     * @internal
+     */
+    private mapBillStatus;
+}
+export default SoftyComp;

package/dist/index.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * SoftyComp Node.js SDK
+ *
+ * Official Node.js SDK for SoftyComp — South African bill presentment and debit order platform.
+ *
+ * @see https://softycompdistribution.co.za
+ * @see https://webapps.softycomp.co.za (API documentation)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SoftyComp = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+// ==================== Main SDK Class ====================
+class SoftyComp {
+    constructor(config) {
+        // Token cache
+        this.token = null;
+        this.tokenExpiry = 0;
+        this.apiKey = config.apiKey;
+        this.secretKey = config.secretKey;
+        this.sandbox = config.sandbox ?? true;
+        this.webhookSecret = config.webhookSecret;
+        // Base URL mapping
+        if (this.sandbox) {
+            this.baseUrl = 'https://sandbox.softycomp.co.za/SoftyCompBureauAPI';
+        }
+        else {
+            this.baseUrl = 'https://api.softycomp.co.za/SoftyCompBureauAPI';
+        }
+        if (!this.apiKey || !this.secretKey) {
+            throw new Error('SoftyComp requires apiKey and secretKey');
+        }
+    }
+    // ==================== Authentication ====================
+    /**
+     * Authenticate and get Bearer token (cached for ~30 minutes)
+     * @internal
+     */
+    async authenticate() {
+        // Return cached token if still valid (with 60s buffer)
+        if (this.token && Date.now() < this.tokenExpiry - 60000) {
+            return this.token;
+        }
+        const response = await fetch(`${this.baseUrl}/api/auth/generatetoken`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                apiKey: this.apiKey,
+                apiSecret: this.secretKey,
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`SoftyComp authentication failed: ${response.status} - ${errorText}`);
+        }
+        const data = (await response.json());
+        this.token = data.token;
+        this.tokenExpiry = new Date(data.expiration).getTime();
+        return this.token;
+    }
+    /**
+     * Make authenticated API request
+     * @internal
+     */
+    async apiRequest(method, path, data) {
+        const token = await this.authenticate();
+        const url = `${this.baseUrl}${path}`;
+        const response = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`SoftyComp API error (${method} ${path}): ${response.status} - ${errorText}`);
+        }
+        const contentType = response.headers.get('content-type');
+        if (contentType && contentType.includes('application/json')) {
+            return (await response.json());
+        }
+        return (await response.text());
+    }
+    // ==================== Bill Presentment ====================
+    /**
+     * Create a payment bill (once-off or recurring)
+     *
+     * @example
+     * ```typescript
+     * const bill = await client.createBill({
+     *   amount: 299.00,
+     *   customerName: 'John Doe',
+     *   customerEmail: 'john@example.com',
+     *   customerPhone: '0825551234',
+     *   reference: 'INV-001',
+     *   description: 'Monthly subscription',
+     *   frequency: 'monthly',
+     *   commencementDate: '2026-04-01',
+     *   recurringDay: 1,
+     *   returnUrl: 'https://myapp.com/success',
+     *   cancelUrl: 'https://myapp.com/cancel',
+     *   notifyUrl: 'https://myapp.com/webhook'
+     * });
+     *
+     * // Redirect customer to payment page
+     * console.log(bill.paymentUrl);
+     * ```
+     */
+    async createBill(params) {
+        const isRecurring = params.frequency !== 'once-off';
+        // Frequency type mapping: 1=once-off, 2=monthly, 7=yearly
+        const frequencyTypeID = params.frequency === 'yearly' ? 7 : params.frequency === 'monthly' ? 2 : 1;
+        // Build the bill item
+        const item = {
+            Description: params.description || 'Payment',
+            Amount: parseFloat(params.amount.toFixed(2)),
+            FrequencyTypeID: frequencyTypeID,
+            DisplayCompanyName: params.companyName || 'Your Company',
+            DisplayCompanyContactNo: params.companyContact || '',
+            DisplayCompanyEmailAddress: params.companyEmail || params.customerEmail,
+        };
+        // Add recurring-specific fields
+        if (isRecurring) {
+            // Validate commencement date is in the future
+            let commencementDate;
+            if (params.commencementDate) {
+                commencementDate = new Date(params.commencementDate);
+                const now = new Date();
+                now.setHours(0, 0, 0, 0);
+                if (commencementDate <= now) {
+                    throw new Error('commencementDate must be a future date (minimum tomorrow)');
+                }
+            }
+            else {
+                // Default to tomorrow
+                commencementDate = new Date();
+                commencementDate.setDate(commencementDate.getDate() + 1);
+            }
+            item.CommencementDate = commencementDate.toISOString().split('T')[0];
+            item.RecurringDay = params.recurringDay || commencementDate.getDate();
+            if (params.frequency === 'yearly') {
+                item.RecurringMonth = params.recurringMonth || (commencementDate.getMonth() + 1);
+            }
+            else {
+                item.RecurringMonth = null;
+            }
+            item.DayOfWeek = null;
+            item.ExpiryDate = null;
+            item.InitialAmount = null;
+            item.ToCollectAmount = null;
+        }
+        // Build the bill request
+        const billData = {
+            Name: params.customerName,
+            ModeTypeID: 4, // Plugin mode (returns payment URL)
+            Emailaddress: params.customerEmail,
+            Cellno: params.customerPhone,
+            UserReference: params.reference,
+            Items: [item],
+            ScheduledDateTime: null,
+            CallbackUrl: params.notifyUrl,
+            SuccessURL: params.returnUrl,
+            FailURL: params.cancelUrl,
+            NotifyURL: params.notifyUrl,
+            CancelURL: params.cancelUrl,
+        };
+        const result = await this.apiRequest('POST', '/api/paygatecontroller/requestbillpresentment', billData);
+        if (!result.success) {
+            throw new Error(`Failed to create bill: ${result.message}`);
+        }
+        return {
+            reference: result.reference,
+            paymentUrl: result.paymentURL,
+            expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
+        };
+    }
+    // ==================== Bill Status ====================
+    /**
+     * Get bill payment status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.getBillStatus('BILL-REF-123');
+     * if (status.status === 'completed') {
+     *   console.log('Payment received on:', status.paidAt);
+     * }
+     * ```
+     */
+    async getBillStatus(reference) {
+        const result = await this.apiRequest('GET', `/api/paygatecontroller/listBillPresentmentDetails/${reference}/${reference}`);
+        // Map status: 1=pending, 2=completed, 3=failed, 4/5=cancelled
+        const statusTypeID = result?.statusTypeID || result?.status || 1;
+        const status = this.mapBillStatus(statusTypeID);
+        return {
+            reference: result?.reference || reference,
+            status,
+            amount: parseFloat(result?.amount || '0'),
+            paidAt: result?.transactionDate || undefined,
+            data: result,
+        };
+    }
+    // ==================== Refunds ====================
+    /**
+     * Process a refund (credit transaction)
+     *
+     * @example
+     * ```typescript
+     * // Full refund
+     * const refund = await client.refund({ transactionId: 'TXN-123' });
+     *
+     * // Partial refund
+     * const refund = await client.refund({
+     *   transactionId: 'TXN-123',
+     *   amount: 100.00
+     * });
+     * ```
+     */
+    async refund(params) {
+        const refundData = {
+            Reference: params.transactionId,
+            UserReference: params.transactionId,
+        };
+        if (params.amount !== undefined) {
+            // IMPORTANT: SoftyComp uses capital "A" in Amount field for refunds
+            refundData.Amount = parseFloat(params.amount.toFixed(2));
+        }
+        const result = await this.apiRequest('POST', '/api/paygatecontroller/requestCreditTransaction', refundData);
+        return {
+            refundId: result?.reference || `refund_${params.transactionId}_${Date.now()}`,
+            status: result?.success ? 'completed' : 'pending',
+            amount: params.amount || 0,
+        };
+    }
+    // ==================== Webhooks ====================
+    /**
+     * Verify webhook signature (HMAC-SHA256)
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const signature = req.headers['x-signature'] as string;
+     *   if (!client.verifyWebhook(req.body, { signature })) {
+     *     return res.status(400).send('Invalid signature');
+     *   }
+     *   // Process webhook...
+     * });
+     * ```
+     */
+    verifyWebhook(body, headers) {
+        const signature = 'signature' in headers ? headers.signature : headers['x-signature'];
+        if (!signature || !this.webhookSecret) {
+            // No signature validation configured
+            return true;
+        }
+        const expectedSignature = crypto_1.default
+            .createHmac('sha256', this.webhookSecret)
+            .update(body)
+            .digest('hex');
+        return signature === expectedSignature || signature === `sha256=${expectedSignature}`;
+    }
+    /**
+     * Parse webhook event payload
+     *
+     * @example
+     * ```typescript
+     * const event = client.parseWebhook(req.body);
+     *
+     * switch (event.type) {
+     *   case 'successful':
+     *     console.log('Payment successful:', event.reference, event.amount);
+     *     break;
+     *   case 'failed':
+     *     console.log('Payment failed:', event.reference);
+     *     break;
+     *   case 'cancelled':
+     *     console.log('Payment cancelled:', event.reference);
+     *     break;
+     * }
+     * ```
+     */
+    parseWebhook(body) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        // activityTypeID mapping: 1=Pending, 2=Successful, 3=Failed, 4=Cancelled
+        let type = 'pending';
+        let status = 'pending';
+        switch (event.activityTypeID) {
+            case 2:
+                type = 'successful';
+                status = 'completed';
+                break;
+            case 3:
+                type = 'failed';
+                status = 'failed';
+                break;
+            case 4:
+                type = 'cancelled';
+                status = 'cancelled';
+                break;
+            default:
+                type = 'pending';
+                status = 'pending';
+        }
+        return {
+            type,
+            reference: event.reference,
+            status,
+            amount: event.amount,
+            transactionDate: event.transactionDate,
+            paymentMethodId: event.paymentMethodTypeID,
+            paymentMethod: event.paymentMethodTypeDescription,
+            userReference: event.userReference,
+            information: event.information,
+            raw: event,
+        };
+    }
+    // ==================== Helpers ====================
+    /**
+     * Map SoftyComp status type ID to payment status
+     * @internal
+     */
+    mapBillStatus(statusTypeID) {
+        switch (Number(statusTypeID)) {
+            case 1: return 'pending'; // New
+            case 2: return 'completed'; // Paid
+            case 3: return 'failed'; // Failed
+            case 4: return 'cancelled'; // Expired
+            case 5: return 'cancelled'; // Cancelled
+            default: return 'pending';
+        }
+    }
+}
+exports.SoftyComp = SoftyComp;
+// ==================== Default Export ====================
+exports.default = SoftyComp;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "softycomp-node",
+  "version": "1.0.0",
+  "description": "Node.js SDK for SoftyComp — South African bill presentment and debit order platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "softycomp",
+    "south-africa",
+    "payments",
+    "debit-order",
+    "billing",
+    "nodejs",
+    "typescript",
+    "zar",
+    "bill-presentment",
+    "recurring-billing"
+  ],
+  "author": "Kobie Wentzel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kobie3717/softycomp-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kobie3717/softycomp-node/issues"
+  },
+  "homepage": "https://github.com/kobie3717/softycomp-node#readme",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.130",
+    "typescript": "^5.9.3"
+  }
+}