@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 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.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. */