@facturino/node 1.0.0

package/dist/cjs/resources/quotes.d.ts

@@ -0,0 +1,44 @@
+import type { HttpClient } from '../client.js';
+import { AutoPaginatingList } from '../pagination.js';
+import type { Quote, QuoteCreateParams, QuoteUpdateParams, QuoteListParams, DocumentUrlResponse, JobResponse, Invoice, RequestOptions } from '../types.js';
+/** Quote lifecycle — create, send, accept or refuse, and convert to invoice. */
+export declare class Quotes {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: QuoteCreateParams, options?: RequestOptions): Promise<Quote>;
+    list(params?: QuoteListParams): AutoPaginatingList<Quote>;
+    get(id: string): Promise<Quote>;
+    update(id: string, params: QuoteUpdateParams): Promise<Quote>;
+    del(id: string): Promise<void>;
+    send(id: string, options?: RequestOptions): Promise<Quote>;
+    /**
+     * Send the quote to its customer by email with the PDF attached. Returns
+     * `{status: 'sent'}` on success or `{status: 'pending'}` if the PDF is
+     * still being generated (caller should poll the returned `jobId`).
+     */
+    email(id: string, params?: {
+        recipientEmail?: string;
+        customMessage?: string;
+        customSubject?: string;
+    }, options?: RequestOptions): Promise<{
+        status: 'sent';
+        quoteId: string;
+        recipient: string;
+        sentAt: string;
+    } | {
+        status: 'pending';
+        quoteId: string;
+        jobId: string;
+        pollUrl: string;
+        reason: string;
+    }>;
+    accept(id: string, options?: RequestOptions): Promise<Quote>;
+    refuse(id: string, options?: RequestOptions): Promise<Quote>;
+    /** Convert accepted quote to draft invoice. */
+    convert(id: string, options?: RequestOptions): Promise<Invoice>;
+    /** Clone as new draft quote. */
+    clone(id: string, options?: RequestOptions): Promise<Quote>;
+    getPdf(id: string): Promise<DocumentUrlResponse | JobResponse>;
+    /** Retrieve the electronic signature proof for an accepted quote. */
+    getSignatureProof(id: string): Promise<DocumentUrlResponse>;
+}

package/dist/cjs/resources/quotes.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Quotes = void 0;
+const pagination_js_1 = require("../pagination.js");
+/** Quote lifecycle — create, send, accept or refuse, and convert to invoice. */
+class Quotes {
+    constructor(client) {
+        this.client = client;
+    }
+    async create(params, options) {
+        return this.client.post('/v1/quotes', params, options);
+    }
+    list(params) {
+        return new pagination_js_1.AutoPaginatingList(this.client, '/v1/quotes', params);
+    }
+    async get(id) {
+        return this.client.get(`/v1/quotes/${id}`);
+    }
+    async update(id, params) {
+        return this.client.patch(`/v1/quotes/${id}`, params);
+    }
+    async del(id) {
+        await this.client.del(`/v1/quotes/${id}`);
+    }
+    async send(id, options) {
+        return this.client.post(`/v1/quotes/${id}/send`, undefined, options);
+    }
+    /**
+     * Send the quote to its customer by email with the PDF attached. Returns
+     * `{status: 'sent'}` on success or `{status: 'pending'}` if the PDF is
+     * still being generated (caller should poll the returned `jobId`).
+     */
+    async email(id, params, options) {
+        return this.client.post(`/v1/quotes/${id}/email`, params, options);
+    }
+    async accept(id, options) {
+        return this.client.post(`/v1/quotes/${id}/accept`, undefined, options);
+    }
+    async refuse(id, options) {
+        return this.client.post(`/v1/quotes/${id}/refuse`, undefined, options);
+    }
+    /** Convert accepted quote to draft invoice. */
+    async convert(id, options) {
+        return this.client.post(`/v1/quotes/${id}/convert`, undefined, options);
+    }
+    /** Clone as new draft quote. */
+    async clone(id, options) {
+        return this.client.post(`/v1/quotes/${id}/clone`, undefined, options);
+    }
+    async getPdf(id) {
+        return this.client.get(`/v1/quotes/${id}/pdf`);
+    }
+    /** Retrieve the electronic signature proof for an accepted quote. */
+    async getSignatureProof(id) {
+        return this.client.get(`/v1/quotes/${id}/signature-proof`);
+    }
+}
+exports.Quotes = Quotes;

package/dist/cjs/resources/received-invoices.d.ts

@@ -0,0 +1,14 @@
+import type { HttpClient } from '../client.js';
+import { AutoPaginatingList } from '../pagination.js';
+import type { ReceivedInvoice, ReceivedInvoiceListParams, ReceivedInvoiceRefuseParams, ReceivedInvoiceRecordPaymentParams, ReceivedInvoiceActionResponse } from '../types.js';
+/** Received (incoming) invoices from PA — list, retrieve, approve, refuse, suspend, record payment. */
+export declare class ReceivedInvoices {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: ReceivedInvoiceListParams): AutoPaginatingList<ReceivedInvoice>;
+    get(id: string): Promise<ReceivedInvoice>;
+    approve(id: string): Promise<ReceivedInvoiceActionResponse>;
+    refuse(id: string, params: ReceivedInvoiceRefuseParams): Promise<ReceivedInvoiceActionResponse>;
+    suspend(id: string): Promise<ReceivedInvoiceActionResponse>;
+    recordPayment(id: string, params: ReceivedInvoiceRecordPaymentParams): Promise<ReceivedInvoiceActionResponse>;
+}

package/dist/cjs/resources/received-invoices.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReceivedInvoices = void 0;
+const pagination_js_1 = require("../pagination.js");
+/** Received (incoming) invoices from PA — list, retrieve, approve, refuse, suspend, record payment. */
+class ReceivedInvoices {
+    constructor(client) {
+        this.client = client;
+    }
+    list(params) {
+        return new pagination_js_1.AutoPaginatingList(this.client, '/v1/received-invoices', params);
+    }
+    async get(id) {
+        return this.client.get(`/v1/received-invoices/${id}`);
+    }
+    async approve(id) {
+        return this.client.post(`/v1/received-invoices/${id}/approve`);
+    }
+    async refuse(id, params) {
+        return this.client.post(`/v1/received-invoices/${id}/refuse`, params);
+    }
+    async suspend(id) {
+        return this.client.post(`/v1/received-invoices/${id}/suspend`);
+    }
+    async recordPayment(id, params) {
+        return this.client.post(`/v1/received-invoices/${id}/record-payment`, params);
+    }
+}
+exports.ReceivedInvoices = ReceivedInvoices;

package/dist/cjs/resources/recurringInvoices.d.ts

@@ -0,0 +1,15 @@
+import type { HttpClient } from '../client.js';
+import { AutoPaginatingList } from '../pagination.js';
+import type { RecurringInvoice, RecurringInvoiceCreateParams, RecurringInvoiceUpdateParams, RecurringInvoiceListParams, RequestOptions } from '../types.js';
+/** Scheduled invoice templates that automatically generate invoices on a recurring basis. */
+export declare class RecurringInvoices {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: RecurringInvoiceCreateParams, options?: RequestOptions): Promise<RecurringInvoice>;
+    list(params?: RecurringInvoiceListParams): AutoPaginatingList<RecurringInvoice>;
+    get(id: string): Promise<RecurringInvoice>;
+    update(id: string, params: RecurringInvoiceUpdateParams): Promise<RecurringInvoice>;
+    del(id: string): Promise<void>;
+    resume(id: string): Promise<RecurringInvoice>;
+    pause(id: string): Promise<RecurringInvoice>;
+}

package/dist/cjs/resources/recurringInvoices.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecurringInvoices = void 0;
+const pagination_js_1 = require("../pagination.js");
+/** Scheduled invoice templates that automatically generate invoices on a recurring basis. */
+class RecurringInvoices {
+    constructor(client) {
+        this.client = client;
+    }
+    async create(params, options) {
+        return this.client.post('/v1/recurring-invoices', params, options);
+    }
+    list(params) {
+        return new pagination_js_1.AutoPaginatingList(this.client, '/v1/recurring-invoices', params);
+    }
+    async get(id) {
+        return this.client.get(`/v1/recurring-invoices/${id}`);
+    }
+    async update(id, params) {
+        return this.client.patch(`/v1/recurring-invoices/${id}`, params);
+    }
+    async del(id) {
+        await this.client.del(`/v1/recurring-invoices/${id}`);
+    }
+    async resume(id) {
+        return this.client.post(`/v1/recurring-invoices/${id}/resume`);
+    }
+    async pause(id) {
+        return this.client.post(`/v1/recurring-invoices/${id}/pause`);
+    }
+}
+exports.RecurringInvoices = RecurringInvoices;

package/dist/cjs/resources/reference.d.ts

@@ -0,0 +1,45 @@
+import type { HttpClient } from '../client.js';
+import type { LegalForm, NafCode, PaProvider, PaginatedResponse } from '../types.js';
+/**
+ * Reference — static lookup tables maintained by INSEE that integrations
+ * need to power their own company / customer forms:
+ *
+ *  - `legalForms` — French legal-form codes (SARL, SAS, EI…)
+ *  - `nafCodes` — French NAF activity codes (Rev. 2, 2008)
+ *
+ * Both lists are stable and cacheable for the lifetime of the
+ * integration's process. The endpoint paginates so the SDK exposes
+ * `listLegalForms()` / `listNafCodes()` returning the full server
+ * response — callers typically fetch once on app start and keep the
+ * result in memory.
+ */
+export declare class Reference {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List INSEE legal forms (4-digit codes + sigles + labels).
+     * Filter by `search` to autocomplete a form field.
+     */
+    listLegalForms(params?: {
+        search?: string;
+        limit?: number;
+    }): Promise<PaginatedResponse<LegalForm>>;
+    /**
+     * List NAF activity codes (Rev. 2). Filter by `search` to
+     * autocomplete on label fragments ("conseil", "transport"…).
+     */
+    listNafCodes(params?: {
+        search?: string;
+        limit?: number;
+    }): Promise<PaginatedResponse<NafCode>>;
+    /**
+     * List the supported Plateformes Agréées (PA). Public catalogue — no auth,
+     * no filter; fetch once and cache. Use it to render a provider picker and the
+     * credential fields each PA requires (Facturino is BYOPA — the customer
+     * brings their own PA credentials at connect time).
+     */
+    listPaProviders(): Promise<{
+        object: 'list';
+        data: PaProvider[];
+    }>;
+}

package/dist/cjs/resources/reference.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Reference = void 0;
+/** Encode a flat object as a `?k=v&…` query string (skips undefined/null). */
+function buildQuery(params) {
+    const entries = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null)
+            continue;
+        entries.push([k, String(v)]);
+    }
+    return entries.length === 0 ? '' : `?${new URLSearchParams(entries).toString()}`;
+}
+/**
+ * Reference — static lookup tables maintained by INSEE that integrations
+ * need to power their own company / customer forms:
+ *
+ *  - `legalForms` — French legal-form codes (SARL, SAS, EI…)
+ *  - `nafCodes` — French NAF activity codes (Rev. 2, 2008)
+ *
+ * Both lists are stable and cacheable for the lifetime of the
+ * integration's process. The endpoint paginates so the SDK exposes
+ * `listLegalForms()` / `listNafCodes()` returning the full server
+ * response — callers typically fetch once on app start and keep the
+ * result in memory.
+ */
+class Reference {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List INSEE legal forms (4-digit codes + sigles + labels).
+     * Filter by `search` to autocomplete a form field.
+     */
+    async listLegalForms(params) {
+        const qs = params ? buildQuery(params) : '';
+        return this.client.get(`/v1/reference/legal-forms${qs}`);
+    }
+    /**
+     * List NAF activity codes (Rev. 2). Filter by `search` to
+     * autocomplete on label fragments ("conseil", "transport"…).
+     */
+    async listNafCodes(params) {
+        const qs = params ? buildQuery(params) : '';
+        return this.client.get(`/v1/reference/naf-codes${qs}`);
+    }
+    /**
+     * List the supported Plateformes Agréées (PA). Public catalogue — no auth,
+     * no filter; fetch once and cache. Use it to render a provider picker and the
+     * credential fields each PA requires (Facturino is BYOPA — the customer
+     * brings their own PA credentials at connect time).
+     */
+    async listPaProviders() {
+        return this.client.get('/v1/pa-providers');
+    }
+}
+exports.Reference = Reference;

package/dist/cjs/resources/reporting.d.ts

@@ -0,0 +1,11 @@
+import type { HttpClient } from '../client.js';
+import type { VatReportParams, VatReport, RevenueReportParams, RevenueReport } from '../types.js';
+/** Financial reporting — VAT and revenue reports (Essential, Pro, Cabinet plans). */
+export declare class Reporting {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** VAT report aggregated by rate for a given period. Amounts in integer centimes. */
+    vatReport(params: VatReportParams): Promise<VatReport>;
+    /** Revenue report with invoiced, credit notes, payments, and optional breakdown. Amounts in integer centimes. */
+    revenueReport(params: RevenueReportParams): Promise<RevenueReport>;
+}

package/dist/cjs/resources/reporting.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Reporting = void 0;
+/** Financial reporting — VAT and revenue reports (Essential, Pro, Cabinet plans). */
+class Reporting {
+    constructor(client) {
+        this.client = client;
+    }
+    /** VAT report aggregated by rate for a given period. Amounts in integer centimes. */
+    async vatReport(params) {
+        const qs = new URLSearchParams({
+            period_start: params.period_start,
+            period_end: params.period_end,
+        }).toString();
+        return this.client.get(`/v1/reporting/vat?${qs}`);
+    }
+    /** Revenue report with invoiced, credit notes, payments, and optional breakdown. Amounts in integer centimes. */
+    async revenueReport(params) {
+        const queryParams = {
+            period_start: params.period_start,
+            period_end: params.period_end,
+        };
+        if (params.group_by) {
+            queryParams.group_by = params.group_by;
+        }
+        const qs = new URLSearchParams(queryParams).toString();
+        return this.client.get(`/v1/reporting/revenue?${qs}`);
+    }
+}
+exports.Reporting = Reporting;

package/dist/cjs/resources/sandbox.d.ts

@@ -0,0 +1,12 @@
+import type { HttpClient } from '../client.js';
+import type { SandboxResetResponse, SimulateStatusParams, SimulateStatusResponse, RequestOptions } from '../types.js';
+/** Test-mode utilities — reset data, simulate PA status transitions, and seed fixtures. */
+export declare class Sandbox {
+    private readonly client;
+    constructor(client: HttpClient);
+    resetData(): Promise<SandboxResetResponse>;
+    /** Simulate PA status transition. Triggers webhooks. */
+    simulateStatus(invoiceId: string, params: SimulateStatusParams, options?: RequestOptions): Promise<SimulateStatusResponse>;
+    /** Alias for resetData(). */
+    createFixtures(): Promise<SandboxResetResponse>;
+}

package/dist/cjs/resources/sandbox.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sandbox = void 0;
+/** Test-mode utilities — reset data, simulate PA status transitions, and seed fixtures. */
+class Sandbox {
+    constructor(client) {
+        this.client = client;
+    }
+    async resetData() {
+        return this.client.post('/v1/sandbox/reset');
+    }
+    /** Simulate PA status transition. Triggers webhooks. */
+    async simulateStatus(invoiceId, params, options) {
+        return this.client.post(`/v1/sandbox/simulate-status/${invoiceId}`, params, options);
+    }
+    /** Alias for resetData(). */
+    async createFixtures() {
+        return this.resetData();
+    }
+}
+exports.Sandbox = Sandbox;

package/dist/cjs/resources/usage.d.ts

@@ -0,0 +1,20 @@
+import type { HttpClient } from '../client.js';
+import type { UsageSummary } from '../types.js';
+/**
+ * Usage — current period consumption metrics for the authenticated
+ * account (invoices issued, storage used, PA submissions, API calls).
+ *
+ * Useful for in-app dashboards and proactive plan-upgrade nudges
+ * before a quota hit triggers a 402 from the API.
+ */
+export declare class Usage {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Return the current usage snapshot. The response includes the plan
+     * limits and the consumption so far for each metered dimension; no
+     * historical data — the dashboard uses `GET /v1/reporting/revenue`
+     * for trend lines.
+     */
+    retrieve(): Promise<UsageSummary>;
+}

package/dist/cjs/resources/usage.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Usage = void 0;
+/**
+ * Usage — current period consumption metrics for the authenticated
+ * account (invoices issued, storage used, PA submissions, API calls).
+ *
+ * Useful for in-app dashboards and proactive plan-upgrade nudges
+ * before a quota hit triggers a 402 from the API.
+ */
+class Usage {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Return the current usage snapshot. The response includes the plan
+     * limits and the consumption so far for each metered dimension; no
+     * historical data — the dashboard uses `GET /v1/reporting/revenue`
+     * for trend lines.
+     */
+    async retrieve() {
+        return this.client.get('/v1/usage');
+    }
+}
+exports.Usage = Usage;

package/dist/cjs/resources/validate.d.ts

@@ -0,0 +1,18 @@
+import type { HttpClient } from '../client.js';
+import type { ValidateParams, ValidateResponse } from '../types.js';
+/**
+ * Validate — dry-run conformity check of an invoice draft against the same
+ * EN16931 / CIUS-FR rules as `invoices.create`, without persisting anything.
+ *
+ * Call it before `invoices.create` to surface conformity warnings early. To
+ * check a customer's SIRET/VAT, use `customers.lookup` (SIRENE/VIES).
+ */
+export declare class Validate {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Validate an invoice payload and return `{ valid, warnings }`. Accepts the
+     * same shape as `invoices.create`; nothing is created.
+     */
+    run(params: ValidateParams): Promise<ValidateResponse>;
+}

package/dist/cjs/resources/validate.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Validate = void 0;
+/**
+ * Validate — dry-run conformity check of an invoice draft against the same
+ * EN16931 / CIUS-FR rules as `invoices.create`, without persisting anything.
+ *
+ * Call it before `invoices.create` to surface conformity warnings early. To
+ * check a customer's SIRET/VAT, use `customers.lookup` (SIRENE/VIES).
+ */
+class Validate {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Validate an invoice payload and return `{ valid, warnings }`. Accepts the
+     * same shape as `invoices.create`; nothing is created.
+     */
+    async run(params) {
+        return this.client.post('/v1/validate', params);
+    }
+}
+exports.Validate = Validate;

package/dist/cjs/resources/webhookEndpoints.d.ts

@@ -0,0 +1,20 @@
+import type { HttpClient } from '../client.js';
+import { AutoPaginatingList } from '../pagination.js';
+import type { WebhookEndpoint, WebhookEndpointCreateParams, WebhookEndpointUpdateParams, PaginationParams, RequestOptions } from '../types.js';
+/** Manages webhook endpoint registrations and their event subscriptions. */
+export declare class WebhookEndpoints {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** Secret only returned on create. */
+    create(params: WebhookEndpointCreateParams, options?: RequestOptions): Promise<WebhookEndpoint>;
+    list(params?: PaginationParams): AutoPaginatingList<WebhookEndpoint>;
+    get(id: string): Promise<WebhookEndpoint>;
+    update(id: string, params: WebhookEndpointUpdateParams): Promise<WebhookEndpoint>;
+    del(id: string): Promise<void>;
+    /** Send a test event to verify the endpoint is reachable. */
+    test(id: string): Promise<{
+        id: string;
+        object: 'webhook_endpoint';
+        status: string;
+    }>;
+}

package/dist/cjs/resources/webhookEndpoints.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEndpoints = void 0;
+const pagination_js_1 = require("../pagination.js");
+/** Manages webhook endpoint registrations and their event subscriptions. */
+class WebhookEndpoints {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Secret only returned on create. */
+    async create(params, options) {
+        return this.client.post('/v1/webhook-endpoints', params, options);
+    }
+    list(params) {
+        return new pagination_js_1.AutoPaginatingList(this.client, '/v1/webhook-endpoints', params);
+    }
+    async get(id) {
+        return this.client.get(`/v1/webhook-endpoints/${id}`);
+    }
+    async update(id, params) {
+        return this.client.patch(`/v1/webhook-endpoints/${id}`, params);
+    }
+    async del(id) {
+        await this.client.del(`/v1/webhook-endpoints/${id}`);
+    }
+    /** Send a test event to verify the endpoint is reachable. */
+    async test(id) {
+        return this.client.post(`/v1/webhook-endpoints/${id}/test`);
+    }
+}
+exports.WebhookEndpoints = WebhookEndpoints;