@robosystems/client 0.2.47 → 0.2.49

package/extensions/LedgerClient.js

@@ -432,7 +432,14 @@ class LedgerClient {
         };
     }
     /**
-     * Create a draft closing entry from a schedule's facts for a period.
+     * Idempotently create (or refresh) a draft closing entry from a schedule's
+     * facts for a period. The `outcome` field describes what actually happened:
+     *
+     * - `created`     — new draft
+     * - `unchanged`   — existing draft still matches the schedule; no-op
+     * - `regenerated` — existing draft was stale; replaced
+     * - `removed`     — schedule no longer covers this period; stale draft deleted
+     * - `skipped`     — no existing draft and no in-scope fact; nothing to do
      */
     async createClosingEntry(graphId, structureId, postingDate, periodStart, periodEnd, memo) {
         const body = {
@@ -449,15 +456,282 @@ class LedgerClient {
             throw new Error(`Create closing entry failed: ${JSON.stringify(response.error)}`);
         }
         const data = response.data;
+        return toClosingEntry(data);
+    }
+    // ── Closing Book ─────────────────────────────────────────────────────
+    /**
+     * Get all closing book structure categories for the sidebar.
+     * Returns statements, account rollups, schedules, trial balance,
+     * and period close grouped into categories.
+     */
+    async getClosingBookStructures(graphId) {
+        const response = await (0, sdk_gen_1.getClosingBookStructures)({
+            path: { graph_id: graphId },
+        });
+        if (response.error) {
+            throw new Error(`Get closing book structures failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    /**
+     * Get account rollups — CoA accounts grouped by reporting element with balances.
+     * Shows how company-specific accounts roll up to standardized reporting lines.
+     */
+    async getAccountRollups(graphId, options) {
+        const response = await (0, sdk_gen_1.getAccountRollups)({
+            path: { graph_id: graphId },
+            query: {
+                mapping_id: options?.mappingId,
+                start_date: options?.startDate,
+                end_date: options?.endDate,
+            },
+        });
+        if (response.error) {
+            throw new Error(`Get account rollups failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    // ── Fiscal Calendar ─────────────────────────────────────────────────
+    /**
+     * Initialize the fiscal calendar for a graph. Creates FiscalPeriod rows
+     * for the data window, sets `closed_through` / `close_target`, and emits
+     * an `initialized` audit event. Fails with 409 if already initialized.
+     */
+    async initializeLedger(graphId, options) {
+        const body = {
+            closed_through: options?.closedThrough ?? null,
+            fiscal_year_start_month: options?.fiscalYearStartMonth,
+            earliest_data_period: options?.earliestDataPeriod ?? null,
+            auto_seed_schedules: options?.autoSeedSchedules,
+            note: options?.note ?? null,
+        };
+        const response = await (0, sdk_gen_1.initializeLedger)({
+            path: { graph_id: graphId },
+            body,
+        });
+        if (response.error) {
+            throw new Error(`Initialize ledger failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
         return {
-            entryId: data.entry_id,
-            status: data.status,
-            postingDate: data.posting_date,
-            memo: data.memo,
-            debitElementId: data.debit_element_id,
-            creditElementId: data.credit_element_id,
-            amount: data.amount,
+            fiscalCalendar: toFiscalCalendarState(data.fiscal_calendar),
+            periodsCreated: data.periods_created ?? 0,
+            warnings: data.warnings ?? [],
         };
     }
+    /**
+     * Get the current fiscal calendar state — pointers, gap, closeable status.
+     */
+    async getFiscalCalendar(graphId) {
+        const response = await (0, sdk_gen_1.getFiscalCalendar)({
+            path: { graph_id: graphId },
+        });
+        if (response.error) {
+            throw new Error(`Get fiscal calendar failed: ${JSON.stringify(response.error)}`);
+        }
+        return toFiscalCalendarState(response.data);
+    }
+    /**
+     * Set the close target for a graph. Validates that the target is not in
+     * the future and not before `closed_through`.
+     */
+    async setCloseTarget(graphId, period, note) {
+        const body = {
+            period,
+            note: note ?? null,
+        };
+        const response = await (0, sdk_gen_1.setCloseTarget)({
+            path: { graph_id: graphId },
+            body,
+        });
+        if (response.error) {
+            throw new Error(`Set close target failed: ${JSON.stringify(response.error)}`);
+        }
+        return toFiscalCalendarState(response.data);
+    }
+    /**
+     * Close a fiscal period — the final commit action.
+     *
+     * Validates closeable gates, transitions all draft entries in the period
+     * to `posted`, marks the FiscalPeriod closed, and advances `closed_through`
+     * (auto-advancing `close_target` when reached).
+     */
+    async closePeriod(graphId, period, options) {
+        const body = {
+            note: options?.note ?? null,
+            allow_stale_sync: options?.allowStaleSync,
+        };
+        const response = await (0, sdk_gen_1.closeFiscalPeriod)({
+            path: { graph_id: graphId, period },
+            body,
+        });
+        if (response.error) {
+            throw new Error(`Close period failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return {
+            period: data.period,
+            entriesPosted: data.entries_posted ?? 0,
+            targetAutoAdvanced: data.target_auto_advanced ?? false,
+            fiscalCalendar: toFiscalCalendarState(data.fiscal_calendar),
+        };
+    }
+    /**
+     * Reopen a closed fiscal period. Requires a non-empty `reason` for the
+     * audit log. Posted entries stay posted; the period transitions to
+     * `closing` so the user can post adjustments and re-close.
+     */
+    async reopenPeriod(graphId, period, reason, note) {
+        const body = {
+            reason,
+            note: note ?? null,
+        };
+        const response = await (0, sdk_gen_1.reopenFiscalPeriod)({
+            path: { graph_id: graphId, period },
+            body,
+        });
+        if (response.error) {
+            throw new Error(`Reopen period failed: ${JSON.stringify(response.error)}`);
+        }
+        return toFiscalCalendarState(response.data);
+    }
+    /**
+     * List all draft entries in a fiscal period for review before close.
+     * Fully expanded with line items, element metadata, and per-entry balance.
+     *
+     * Pure read — call repeatedly without side effects.
+     */
+    async listPeriodDrafts(graphId, period) {
+        const response = await (0, sdk_gen_1.listPeriodDrafts)({
+            path: { graph_id: graphId, period },
+        });
+        if (response.error) {
+            throw new Error(`List period drafts failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return {
+            period: data.period,
+            periodStart: data.period_start,
+            periodEnd: data.period_end,
+            draftCount: data.draft_count,
+            totalDebit: data.total_debit,
+            totalCredit: data.total_credit,
+            allBalanced: data.all_balanced,
+            drafts: (data.drafts ?? []).map((d) => ({
+                entryId: d.entry_id,
+                postingDate: d.posting_date,
+                type: d.type,
+                memo: d.memo ?? null,
+                provenance: d.provenance ?? null,
+                sourceStructureId: d.source_structure_id ?? null,
+                sourceStructureName: d.source_structure_name ?? null,
+                lineItems: d.line_items.map((li) => ({
+                    lineItemId: li.line_item_id,
+                    elementId: li.element_id,
+                    elementCode: li.element_code ?? null,
+                    elementName: li.element_name,
+                    debitAmount: li.debit_amount,
+                    creditAmount: li.credit_amount,
+                    description: li.description ?? null,
+                })),
+                totalDebit: d.total_debit,
+                totalCredit: d.total_credit,
+                balanced: d.balanced,
+            })),
+        };
+    }
+    // ── Schedule mutations ──────────────────────────────────────────────
+    /**
+     * Truncate a schedule — end it early by deleting facts with
+     * `period_start > new_end_date`, along with any stale draft entries they
+     * produced. Historical posted facts are preserved.
+     *
+     * `new_end_date` must be a month-end date (service enforces this).
+     */
+    async truncateSchedule(graphId, structureId, options) {
+        const body = {
+            new_end_date: options.newEndDate,
+            reason: options.reason,
+        };
+        const response = await (0, sdk_gen_1.truncateSchedule)({
+            path: { graph_id: graphId, structure_id: structureId },
+            body,
+        });
+        if (response.error) {
+            throw new Error(`Truncate schedule failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return {
+            structureId: data.structure_id,
+            newEndDate: data.new_end_date,
+            factsDeleted: data.facts_deleted,
+            reason: data.reason,
+        };
+    }
+    /**
+     * Create a manual draft closing entry with arbitrary balanced line items.
+     * Not tied to a schedule — used for disposals, adjustments, and other
+     * one-off closing events.
+     *
+     * Line items must sum to balanced debits/credits. Rejects entries
+     * targeting an already-closed period.
+     */
+    async createManualClosingEntry(graphId, options) {
+        const body = {
+            posting_date: options.postingDate,
+            memo: options.memo,
+            entry_type: options.entryType,
+            line_items: options.lineItems.map((li) => ({
+                element_id: li.elementId,
+                debit_amount: li.debitAmount ?? 0,
+                credit_amount: li.creditAmount ?? 0,
+                description: li.description ?? null,
+            })),
+        };
+        const response = await (0, sdk_gen_1.createManualClosingEntry)({
+            path: { graph_id: graphId },
+            body,
+        });
+        if (response.error) {
+            throw new Error(`Create manual closing entry failed: ${JSON.stringify(response.error)}`);
+        }
+        return toClosingEntry(response.data);
+    }
 }
 exports.LedgerClient = LedgerClient;
+// ── Internal helpers ──────────────────────────────────────────────────
+function toClosingEntry(data) {
+    return {
+        outcome: data.outcome,
+        entryId: data.entry_id ?? null,
+        status: data.status ?? null,
+        postingDate: data.posting_date ?? null,
+        memo: data.memo ?? null,
+        debitElementId: data.debit_element_id ?? null,
+        creditElementId: data.credit_element_id ?? null,
+        amount: data.amount ?? null,
+        reason: data.reason ?? null,
+    };
+}
+function toFiscalCalendarState(data) {
+    return {
+        graphId: data.graph_id,
+        fiscalYearStartMonth: data.fiscal_year_start_month,
+        closedThrough: data.closed_through ?? null,
+        closeTarget: data.close_target ?? null,
+        gapPeriods: data.gap_periods ?? 0,
+        catchUpSequence: data.catch_up_sequence ?? [],
+        closeableNow: data.closeable_now ?? false,
+        blockers: data.blockers ?? [],
+        lastCloseAt: data.last_close_at ?? null,
+        initializedAt: data.initialized_at ?? null,
+        lastSyncAt: data.last_sync_at ?? null,
+        periods: (data.periods ?? []).map((p) => ({
+            name: p.name,
+            startDate: p.start_date,
+            endDate: p.end_date,
+            status: p.status,
+            closedAt: p.closed_at ?? null,
+        })),
+    };
+}