@facturino/node 2.0.0 → 2.1.0

package/dist/esm/resources/euThresholdLedgers.d.ts

@@ -0,0 +1,99 @@
+import type { HttpClient } from '../client.js';
+import type { EuThresholdAdjustmentParams, EuThresholdCorrectionParams, EuThresholdEntryListParams, EuThresholdLedger, EuThresholdLedgerEntryList, EuThresholdReviewParams, EuThresholdReviewResolutionParams, OpenEuThresholdLedgerParams, RequestOptions } from '../types.js';
+/**
+ * The annual EU threshold ledger — the running total the common EUR 10,000
+ * threshold is assessed on.
+ *
+ * It is deliberately separate from the seller's fiscal profile: a profile
+ * revision is an immutable RULE that decisions freeze, while a turnover total
+ * moves with every sale and gets corrected. Keeping them apart is what lets a
+ * correction be recorded without rewriting the rule a frozen decision was taken
+ * under.
+ *
+ * It carries TWO counters, strictly apart and INDEPENDENT: the common
+ * EUR 10,000 threshold (art. 59c(1) — distance sales of goods AND cross-border
+ * services to consumers) and the EUR 100,000 location-evidence threshold
+ * (Reg. 282/2011 art. 24b — electronically supplied services, domestic ones
+ * included). Reading one off the other would open a single-evidence regime on
+ * turnover the regulation does not count towards it, and neither bounds the
+ * other: a seller whose electronic services are mostly domestic legitimately
+ * declares more on the second than on the first.
+ *
+ * Nothing is assumed. Opening a year declares four figures — the two totals and
+ * their services part — plus whether every covered sale goes through Facturino.
+ * Sales made elsewhere are never assumed absent: under `mixed_channels` they
+ * enter through adjustments, and the ledger serves a decision only up to the day
+ * those channels are declared complete through.
+ *
+ * The ledger is append-only: there is no update and no delete. Giving an amount
+ * back is a qualified CORRECTION, which names the movement it corrects; what
+ * cannot be qualified that way puts the ledger under review instead.
+ */
+export declare class EuThresholdLedgers {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Open a calendar year.
+     *
+     * A year already open is never rewritten (`eu_threshold_year_already_open`):
+     * decisions were frozen on its opening figures.
+     */
+    open(params: OpenEuThresholdLedgerParams, options?: RequestOptions): Promise<EuThresholdLedger>;
+    /**
+     * Read the ledger of a year: acquired totals, held slices, what remains, and
+     * the first page of movements.
+     */
+    retrieve(year: string, params?: EuThresholdEntryListParams): Promise<EuThresholdLedger>;
+    /** Alias of {@link retrieve}. */
+    get(year: string): Promise<EuThresholdLedger>;
+    /**
+     * Walk the movements page by page, newest first.
+     *
+     * The ledger keeps every movement; a page shows some. `next_cursor` names the
+     * last one returned.
+     */
+    listEntries(year: string, params?: EuThresholdEntryListParams): Promise<EuThresholdLedgerEntryList>;
+    /**
+     * Record turnover made on another channel.
+     *
+     * Append-only and idempotent on your own `reference`, compared through a
+     * canonical fingerprint of the WHOLE body: replaying the same adjustment adds
+     * nothing, and reusing the reference for any different fact answers
+     * `eu_threshold_entry_conflict`. A negative amount is impossible here —
+     * giving an amount back is {@link correct}.
+     */
+    adjust(year: string, params: EuThresholdAdjustmentParams, options?: RequestOptions): Promise<EuThresholdLedger>;
+    /**
+     * Take a qualified amount back out of the running total.
+     *
+     * Directive 2006/112/EC art. 90(1) reduces the taxable amount of a supply on
+     * cancellation, refusal or a price reduction after the supply, and the
+     * thresholds count the VALUE of the supplies — so the correction names the
+     * movement it corrects (`correctsEntryId`), its qualification, the resource it
+     * rests on and its evidence. The ledger keeps the BALANCE of each movement
+     * inside the transaction, so the corrections of one movement never add up to
+     * more than it brought in (`eu_threshold_correction_exceeds_counted`); an
+     * unknown movement answers `eu_threshold_correction_target_unknown`, and one
+     * that brought no turnover in `eu_threshold_correction_target_not_correctable`.
+     * Each entry publishes its `remainingMin`, so the balance is readable before
+     * the correction is attempted.
+     *
+     * Decisions already frozen are never rewritten: they were correct on the
+     * figures of their own day. Only the total the NEXT operations read changes.
+     */
+    correct(year: string, params: EuThresholdCorrectionParams, options?: RequestOptions): Promise<EuThresholdLedger>;
+    /**
+     * Stop deciding on this ledger: its running total is known to be wrong.
+     *
+     * Every reservation then answers `eu_threshold_review_required`. This is the
+     * honest exit when an amount must come out and no qualified correction can
+     * name the movement it corrects.
+     */
+    review(year: string, params: EuThresholdReviewParams, options?: RequestOptions): Promise<EuThresholdLedger>;
+    /**
+     * Serve decisions again — on a RECONCILIATION that matches, never on a
+     * comment. See {@link EuThresholdReviewResolutionParams}.
+     */
+    resolveReview(year: string, params: EuThresholdReviewResolutionParams, options?: RequestOptions): Promise<EuThresholdLedger>;
+}
+//# sourceMappingURL=euThresholdLedgers.d.ts.map

package/dist/esm/resources/euThresholdLedgers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"euThresholdLedgers.d.ts","sourceRoot":"","sources":["../../../src/resources/euThresholdLedgers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,EACvB,iCAAiC,EACjC,2BAA2B,EAC3B,cAAc,EACf,MAAM,aAAa,CAAA;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAE/C;;;;;OAKG;IACG,IAAI,CACR,MAAM,EAAE,2BAA2B,EACnC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC;IAI7B;;;OAGG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAM7F,iCAAiC;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAInD;;;;;OAKG;IACG,WAAW,CACf,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,CAAC;IAMtC;;;;;;;;OAQG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,2BAA2B,EACnC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC;IAQ7B;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,2BAA2B,EACnC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC;IAQ7B;;;;;;OAMG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,uBAAuB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC;IAQ7B;;;OAGG;IACG,aAAa,CACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iCAAiC,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC;CAO9B"}

package/dist/esm/resources/euThresholdLedgers.js

@@ -0,0 +1,126 @@
+/**
+ * The annual EU threshold ledger — the running total the common EUR 10,000
+ * threshold is assessed on.
+ *
+ * It is deliberately separate from the seller's fiscal profile: a profile
+ * revision is an immutable RULE that decisions freeze, while a turnover total
+ * moves with every sale and gets corrected. Keeping them apart is what lets a
+ * correction be recorded without rewriting the rule a frozen decision was taken
+ * under.
+ *
+ * It carries TWO counters, strictly apart and INDEPENDENT: the common
+ * EUR 10,000 threshold (art. 59c(1) — distance sales of goods AND cross-border
+ * services to consumers) and the EUR 100,000 location-evidence threshold
+ * (Reg. 282/2011 art. 24b — electronically supplied services, domestic ones
+ * included). Reading one off the other would open a single-evidence regime on
+ * turnover the regulation does not count towards it, and neither bounds the
+ * other: a seller whose electronic services are mostly domestic legitimately
+ * declares more on the second than on the first.
+ *
+ * Nothing is assumed. Opening a year declares four figures — the two totals and
+ * their services part — plus whether every covered sale goes through Facturino.
+ * Sales made elsewhere are never assumed absent: under `mixed_channels` they
+ * enter through adjustments, and the ledger serves a decision only up to the day
+ * those channels are declared complete through.
+ *
+ * The ledger is append-only: there is no update and no delete. Giving an amount
+ * back is a qualified CORRECTION, which names the movement it corrects; what
+ * cannot be qualified that way puts the ledger under review instead.
+ */
+export class EuThresholdLedgers {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Open a calendar year.
+     *
+     * A year already open is never rewritten (`eu_threshold_year_already_open`):
+     * decisions were frozen on its opening figures.
+     */
+    async open(params, options) {
+        return this.client.post('/v1/eu-threshold-ledgers', params, options);
+    }
+    /**
+     * Read the ledger of a year: acquired totals, held slices, what remains, and
+     * the first page of movements.
+     */
+    async retrieve(year, params) {
+        return this.client.get(`/v1/eu-threshold-ledgers/${year}${toQuery(params)}`);
+    }
+    /** Alias of {@link retrieve}. */
+    async get(year) {
+        return this.retrieve(year);
+    }
+    /**
+     * Walk the movements page by page, newest first.
+     *
+     * The ledger keeps every movement; a page shows some. `next_cursor` names the
+     * last one returned.
+     */
+    async listEntries(year, params) {
+        return this.client.get(`/v1/eu-threshold-ledgers/${year}/entries${toQuery(params)}`);
+    }
+    /**
+     * Record turnover made on another channel.
+     *
+     * Append-only and idempotent on your own `reference`, compared through a
+     * canonical fingerprint of the WHOLE body: replaying the same adjustment adds
+     * nothing, and reusing the reference for any different fact answers
+     * `eu_threshold_entry_conflict`. A negative amount is impossible here —
+     * giving an amount back is {@link correct}.
+     */
+    async adjust(year, params, options) {
+        return this.client.post(`/v1/eu-threshold-ledgers/${year}/adjustments`, params, options);
+    }
+    /**
+     * Take a qualified amount back out of the running total.
+     *
+     * Directive 2006/112/EC art. 90(1) reduces the taxable amount of a supply on
+     * cancellation, refusal or a price reduction after the supply, and the
+     * thresholds count the VALUE of the supplies — so the correction names the
+     * movement it corrects (`correctsEntryId`), its qualification, the resource it
+     * rests on and its evidence. The ledger keeps the BALANCE of each movement
+     * inside the transaction, so the corrections of one movement never add up to
+     * more than it brought in (`eu_threshold_correction_exceeds_counted`); an
+     * unknown movement answers `eu_threshold_correction_target_unknown`, and one
+     * that brought no turnover in `eu_threshold_correction_target_not_correctable`.
+     * Each entry publishes its `remainingMin`, so the balance is readable before
+     * the correction is attempted.
+     *
+     * Decisions already frozen are never rewritten: they were correct on the
+     * figures of their own day. Only the total the NEXT operations read changes.
+     */
+    async correct(year, params, options) {
+        return this.client.post(`/v1/eu-threshold-ledgers/${year}/corrections`, params, options);
+    }
+    /**
+     * Stop deciding on this ledger: its running total is known to be wrong.
+     *
+     * Every reservation then answers `eu_threshold_review_required`. This is the
+     * honest exit when an amount must come out and no qualified correction can
+     * name the movement it corrects.
+     */
+    async review(year, params, options) {
+        return this.client.post(`/v1/eu-threshold-ledgers/${year}/review`, params, options);
+    }
+    /**
+     * Serve decisions again — on a RECONCILIATION that matches, never on a
+     * comment. See {@link EuThresholdReviewResolutionParams}.
+     */
+    async resolveReview(year, params, options) {
+        return this.client.post(`/v1/eu-threshold-ledgers/${year}/review/resolve`, params, options);
+    }
+}
+/** Query string for the cursor pagination, empty when nothing is asked. */
+function toQuery(params) {
+    if (params === undefined)
+        return '';
+    const search = new URLSearchParams();
+    if (params.limit !== undefined)
+        search.set('limit', String(params.limit));
+    if (params.starting_after !== undefined)
+        search.set('starting_after', params.starting_after);
+    const query = search.toString();
+    return query === '' ? '' : `?${query}`;
+}
+//# sourceMappingURL=euThresholdLedgers.js.map

package/dist/esm/resources/euThresholdLedgers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"euThresholdLedgers.js","sourceRoot":"","sources":["../../../src/resources/euThresholdLedgers.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,kBAAkB;IAC7B,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CACR,MAAmC,EACnC,OAAwB;QAExB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAoB,0BAA0B,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;IACzF,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,MAAmC;QAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CACpB,4BAA4B,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CACrD,CAAA;IACH,CAAC;IAED,iCAAiC;IACjC,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC5B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,WAAW,CACf,IAAY,EACZ,MAAmC;QAEnC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CACpB,4BAA4B,IAAI,WAAW,OAAO,CAAC,MAAM,CAAC,EAAE,CAC7D,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CACV,IAAY,EACZ,MAAmC,EACnC,OAAwB;QAExB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,4BAA4B,IAAI,cAAc,EAC9C,MAAM,EACN,OAAO,CACR,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,OAAO,CACX,IAAY,EACZ,MAAmC,EACnC,OAAwB;QAExB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,4BAA4B,IAAI,cAAc,EAC9C,MAAM,EACN,OAAO,CACR,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CACV,IAAY,EACZ,MAA+B,EAC/B,OAAwB;QAExB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,4BAA4B,IAAI,SAAS,EACzC,MAAM,EACN,OAAO,CACR,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CACjB,IAAY,EACZ,MAAyC,EACzC,OAAwB;QAExB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,4BAA4B,IAAI,iBAAiB,EACjD,MAAM,EACN,OAAO,CACR,CAAA;IACH,CAAC;CACF;AAED,2EAA2E;AAC3E,SAAS,OAAO,CAAC,MAAmC;IAClD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IACpC,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IACzE,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,cAAc,CAAC,CAAA;IAC5F,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;IAC/B,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAA;AACxC,CAAC"}