Bill Management

The billManager provides methods to create and manage both one-time and recurring bills.

Fetching Bills

Fetch Single Bill

const bill = await client.billManager.fetchBill(billId, {
	includeBalance: true, // Include current balance
	includeRecords: true, // Include payment records
});

Fetch Multiple Bills

const bills = await client.billManager.fetchBills([billId1, billId2], {
	includeBalance: true,
	includeRecords: true,
});

Creating Bills

Create One-time Bill

const { resp, billObjChange } = await client.billManager.createBill(
	coinType, // e.g., "0x2::sui::SUI"
	amount, // Amount in smallest unit
	payers, // Array of nominated payer addresses (optional)
	billManager, // Address that can manage the bill
	description, // Bill description
	{
		type: 'regular', // One-time bill
	},
);

Create Recurring Bill

const { resp, billObjChange } = await client.billManager.createBill(
	coinType,
	amount, // Amount per interval
	payers,
	billManager,
	description,
	{
		type: 'recurring',
		interval: 2592000000, // Interval in milliseconds (e.g., 30 days)
	},
);

Managing Bills

Pay Bill

const resp = await client.billManager.payBill(
	coinType, // Token type to pay with
	billId, // ID of the bill to pay
	amount, // Amount to pay
	{
		dryRun, // Optional: Simulate transaction
		sender, // Optional: Override default sender
	},
);

Cancel Bill

const resp = await client.billManager.cancelBill(
	billId, // ID of the bill to cancel
	{
		dryRun, // Optional: Simulate transaction
		sender, // Optional: Override default sender
	},
);

Reject Bill

const resp = await client.billManager.rejectBill(
	billId, // ID of the bill to reject
	{
		dryRun, // Optional: Simulate transaction
		sender, // Optional: Override default sender
	},
);

Claim Payment

const resp = await client.billManager.claimPayment(
	coinType, // Token type
	billId, // ID of the bill
	receiver, // Address to receive the payment
	{
		dryRun, // Optional: Simulate transaction
		sender, // Optional: Override default sender
	},
);

Claim Back Payment

const resp = await client.billManager.claimBackPayment(
	coinType, // Token type
	billId, // ID of the bill
	indices, // Array of payment indices to claim back
	receiver, // Address to receive the refund
	{
		dryRun, // Optional: Simulate transaction
		sender, // Optional: Override default sender
	},
);

Bill Objects

Bills returned by the SDK include:

interface Bill {
	id: string;
	amount: bigint;
	creator: string;
	bill_manager: string;
	nominated_payers: string[];
	coin_type: string;
	payment_records: PaymentRecord[];
	paid_amount: bigint;
	description: string;
	creation_time: number;
	status: number;
	// Status flags
	is_inprogress: boolean;
	is_paid: boolean;
	is_completed: boolean;
	is_canceled: boolean;
	is_rejected: boolean;
}

interface RecurringBill extends Bill {
	pending_amount: bigint;
	completed_payments: number;
	expires_at: number;
	interval: number;
	// Status flags
	is_inprogress: boolean;
	is_canceled: boolean;
	is_rejected: boolean;
}

Status Values

• 0: INPROGRESS - Bill is active and accepting payments

• 1: PAID - Bill has received full payment (one-time bills only)

• 2: COMPLETED - Bill has been claimed (one-time bills only)

• 3: CANCELED - Bill has been canceled

• 4: REJECTED - Bill has been rejected

Error Handling

Handle specific bill management errors:

try {
	await client.billManager.payBill(/* ... */);
} catch (error) {
	switch (error.code) {
		case 'UNSUPPORTED_COIN':
			// Handle unsupported coin type
			break;
		case 'INSUFFICIENT_BALANCE':
			// Handle insufficient balance
			break;
		case 'INVALID_STATE':
			// Handle invalid bill state
			break;
		case 'PERMISSION_DENIED':
			// Handle permission issues
			break;
		default:
		// Handle other errors
	}
}

Common Use Cases

1. Create and Track Bill:

// Create bill
const { billObjChange } = await client.billManager.createBill(/* ... */);
const billId = billObjChange.id;

// Monitor status
const bill = await client.billManager.fetchBill(billId);
console.log('Bill Status:', bill.status);

1. Pay and Claim Bill:

// Pay bill
await client.billManager.payBill(coinType, billId, amount);

// Claim payment when paid
const bill = await client.billManager.fetchBill(billId);
if (bill.is_paid) {
	await client.billManager.claimPayment(coinType, billId, receiver);
}