@neuctra/finance 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -0
- package/package.json +1 -1
- package/src/index.d.ts +82 -0
- package/src/index.js +14 -0
package/README.md
CHANGED
|
@@ -99,6 +99,27 @@ await finance.debts.list({ status: "open" });
|
|
|
99
99
|
|
|
100
100
|
Amounts are in major units with the currency's decimals (`1500.5` means 1,500.50; yen has none).
|
|
101
101
|
|
|
102
|
+
## Invoices
|
|
103
|
+
|
|
104
|
+
Invoice reads need `read`; invoice changes need the `invoices:write` permission.
|
|
105
|
+
Payments are recorded as income in the account you choose, and the key's allowed
|
|
106
|
+
accounts and per-transaction limit are enforced for that payment.
|
|
107
|
+
|
|
108
|
+
```js
|
|
109
|
+
const draft = await finance.invoices.create({
|
|
110
|
+
customer: { name: "Acme Ltd", email: "billing@acme.test" },
|
|
111
|
+
lines: [{ description: "Consulting", quantity: 2, unitPrice: 500, taxRate: 10 }],
|
|
112
|
+
dueDate: "2026-12-01",
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
const { invoice, emailed } = await finance.invoices.send(draft.id, { email: true });
|
|
116
|
+
const payment = await finance.invoices.pay(invoice.id, { accountId, amount: 500 });
|
|
117
|
+
console.log(payment.invoice.due, payment.account.balance);
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Drafts can be updated or deleted. A sent invoice can be voided only if it has no
|
|
121
|
+
payments; invoice payments can be partial but cannot exceed the amount due.
|
|
122
|
+
|
|
102
123
|
## Webhooks
|
|
103
124
|
|
|
104
125
|
Your server gets a signed POST when money moves, a hold changes or a request is decided. Check
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@neuctra/finance",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Record expenses, income, transfers and debts, reserve money with holds and ask for spending approval against your Neuctra Finance accounts from any JavaScript app.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/index.js",
|
package/src/index.d.ts
CHANGED
|
@@ -18,6 +18,7 @@ export type Scope =
|
|
|
18
18
|
| "income:write"
|
|
19
19
|
| "transfers:write"
|
|
20
20
|
| "debts:write"
|
|
21
|
+
| "invoices:write"
|
|
21
22
|
| "holds:write"
|
|
22
23
|
| "requests:write"
|
|
23
24
|
| "reversals:write";
|
|
@@ -253,6 +254,77 @@ export interface SpendRequestInput {
|
|
|
253
254
|
idempotencyKey?: string;
|
|
254
255
|
}
|
|
255
256
|
|
|
257
|
+
export interface InvoiceLineInput {
|
|
258
|
+
description: string;
|
|
259
|
+
unitPrice: number;
|
|
260
|
+
quantity?: number;
|
|
261
|
+
/** Percentage from 0 to 100. */
|
|
262
|
+
taxRate?: number;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
export interface InvoiceInput {
|
|
266
|
+
customer: { name: string; email?: string; address?: string };
|
|
267
|
+
lines: InvoiceLineInput[];
|
|
268
|
+
issueDate?: string;
|
|
269
|
+
dueDate?: string;
|
|
270
|
+
taxLabel?: string;
|
|
271
|
+
category?: string;
|
|
272
|
+
notes?: string;
|
|
273
|
+
idempotencyKey?: string;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
export interface Invoice {
|
|
277
|
+
id: string;
|
|
278
|
+
number: string | null;
|
|
279
|
+
status: "draft" | "sent" | "paid" | "void";
|
|
280
|
+
isOverdue: boolean;
|
|
281
|
+
customer: { name: string; email: string | null; address: string | null };
|
|
282
|
+
issueDate: string;
|
|
283
|
+
dueDate: string;
|
|
284
|
+
currency: string;
|
|
285
|
+
lines: Array<{
|
|
286
|
+
description: string;
|
|
287
|
+
quantity: number;
|
|
288
|
+
unitPrice: number;
|
|
289
|
+
taxRate: number;
|
|
290
|
+
amount: number;
|
|
291
|
+
tax: number;
|
|
292
|
+
}>;
|
|
293
|
+
taxLabel: string;
|
|
294
|
+
subtotal: number;
|
|
295
|
+
tax: number;
|
|
296
|
+
total: number;
|
|
297
|
+
paid: number;
|
|
298
|
+
due: number;
|
|
299
|
+
category: string | null;
|
|
300
|
+
notes: string | null;
|
|
301
|
+
sentAt: string | null;
|
|
302
|
+
lastEmailedAt: string | null;
|
|
303
|
+
paidAt: string | null;
|
|
304
|
+
voidedAt: string | null;
|
|
305
|
+
voidReason: string | null;
|
|
306
|
+
createdAt: string | null;
|
|
307
|
+
link: string | null;
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
export interface InvoicePaymentInput extends MovementDetails {
|
|
311
|
+
accountId: string;
|
|
312
|
+
amount: number;
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
export interface InvoicePaymentResult {
|
|
316
|
+
invoice: Invoice;
|
|
317
|
+
transaction: Transaction;
|
|
318
|
+
account: Account;
|
|
319
|
+
replayed: boolean;
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
export interface InvoiceSendResult {
|
|
323
|
+
invoice: Invoice;
|
|
324
|
+
emailed: boolean;
|
|
325
|
+
emailError: string | null;
|
|
326
|
+
}
|
|
327
|
+
|
|
256
328
|
export interface Page<T> {
|
|
257
329
|
data: T[];
|
|
258
330
|
nextCursor: string | null;
|
|
@@ -317,6 +389,16 @@ export declare class NeuctraFinance {
|
|
|
317
389
|
create(input: CreateDebtInput): Promise<DebtResult>;
|
|
318
390
|
pay(debtId: string, input: DebtPaymentInput): Promise<DebtResult | MovementResult>;
|
|
319
391
|
};
|
|
392
|
+
invoices: {
|
|
393
|
+
list(): Promise<Invoice[]>;
|
|
394
|
+
get(invoiceId: string): Promise<Invoice>;
|
|
395
|
+
create(input: InvoiceInput): Promise<Invoice>;
|
|
396
|
+
update(invoiceId: string, input: Partial<InvoiceInput>): Promise<Invoice>;
|
|
397
|
+
delete(invoiceId: string): Promise<void>;
|
|
398
|
+
send(invoiceId: string, input?: { email?: boolean }): Promise<InvoiceSendResult>;
|
|
399
|
+
pay(invoiceId: string, input: InvoicePaymentInput): Promise<InvoicePaymentResult>;
|
|
400
|
+
void(invoiceId: string, input: { reason: string }): Promise<Invoice>;
|
|
401
|
+
};
|
|
320
402
|
}
|
|
321
403
|
|
|
322
404
|
export interface WebhookEvent<T = Record<string, any>> {
|
package/src/index.js
CHANGED
|
@@ -124,6 +124,20 @@ export class NeuctraFinance {
|
|
|
124
124
|
/** Pays a payable or collects a receivable, fully or in part. */
|
|
125
125
|
pay: (debtId, input) => this.write(`/v1/debts/${enc(debtId)}/payments`, input),
|
|
126
126
|
};
|
|
127
|
+
|
|
128
|
+
this.invoices = {
|
|
129
|
+
list: () => this.request("GET", "/v1/invoices").then((r) => r.data),
|
|
130
|
+
get: (invoiceId) => this.request("GET", `/v1/invoices/${enc(invoiceId)}`).then((r) => r.invoice),
|
|
131
|
+
create: (input) => this.write("/v1/invoices", input).then((r) => r.invoice),
|
|
132
|
+
update: (invoiceId, input) =>
|
|
133
|
+
this.request("PATCH", `/v1/invoices/${enc(invoiceId)}`, { body: input }).then((r) => r.invoice),
|
|
134
|
+
delete: (invoiceId) => this.request("DELETE", `/v1/invoices/${enc(invoiceId)}`).then(() => undefined),
|
|
135
|
+
/** Assigns an invoice number and optionally emails its link to the customer. */
|
|
136
|
+
send: (invoiceId, input = {}) => this.write(`/v1/invoices/${enc(invoiceId)}/send`, input),
|
|
137
|
+
/** Records a partial or full payment in the chosen account. */
|
|
138
|
+
pay: (invoiceId, input) => this.write(`/v1/invoices/${enc(invoiceId)}/payments`, input),
|
|
139
|
+
void: (invoiceId, input) => this.write(`/v1/invoices/${enc(invoiceId)}/void`, input).then((r) => r.invoice),
|
|
140
|
+
};
|
|
127
141
|
}
|
|
128
142
|
|
|
129
143
|
/** The business and permissions this key belongs to. */
|