@robosystems/client 0.2.48 → 0.2.49

package/extensions/LedgerClient.d.ts

@@ -67,14 +67,128 @@ export interface PeriodCloseStatus {
     totalDraft: number;
     totalPosted: number;
 }
+/**
+ * Outcome of an idempotent `createClosingEntry` call.
+ *
+ * - `created`     — no prior draft, new draft created
+ * - `unchanged`   — prior draft matches current schedule fact, no-op
+ * - `regenerated` — prior draft was stale, replaced with a fresh one
+ * - `removed`     — prior draft existed but schedule no longer covers this period
+ * - `skipped`     — no prior draft and no in-scope fact; nothing to do
+ */
+export type ClosingEntryOutcome = 'created' | 'unchanged' | 'regenerated' | 'removed' | 'skipped';
+/**
+ * Result of an idempotent closing-entry call. `entry_id`, `amount`, and
+ * related fields are null for `removed` and `skipped` outcomes.
+ */
 export interface ClosingEntry {
-    entryId: string;
+    outcome: ClosingEntryOutcome;
+    entryId: string | null;
+    status: string | null;
+    postingDate: string | null;
+    memo: string | null;
+    debitElementId: string | null;
+    creditElementId: string | null;
+    amount: number | null;
+    reason: string | null;
+}
+export type LedgerEntryType = 'standard' | 'adjusting' | 'closing' | 'reversing';
+export interface FiscalPeriodSummary {
+    name: string;
+    startDate: string;
+    endDate: string;
     status: string;
+    closedAt: string | null;
+}
+export interface FiscalCalendarState {
+    graphId: string;
+    fiscalYearStartMonth: number;
+    closedThrough: string | null;
+    closeTarget: string | null;
+    gapPeriods: number;
+    catchUpSequence: string[];
+    closeableNow: boolean;
+    blockers: string[];
+    lastCloseAt: string | null;
+    initializedAt: string | null;
+    lastSyncAt: string | null;
+    periods: FiscalPeriodSummary[];
+}
+export interface InitializeLedgerOptions {
+    closedThrough?: string | null;
+    fiscalYearStartMonth?: number;
+    earliestDataPeriod?: string | null;
+    autoSeedSchedules?: boolean;
+    note?: string | null;
+}
+export interface InitializeLedgerResult {
+    fiscalCalendar: FiscalCalendarState;
+    periodsCreated: number;
+    warnings: string[];
+}
+export interface ClosePeriodOptions {
+    note?: string | null;
+    allowStaleSync?: boolean;
+}
+export interface ClosePeriodResult {
+    period: string;
+    entriesPosted: number;
+    targetAutoAdvanced: boolean;
+    fiscalCalendar: FiscalCalendarState;
+}
+export interface DraftLineItemView {
+    lineItemId: string;
+    elementId: string;
+    elementCode: string | null;
+    elementName: string;
+    debitAmount: number;
+    creditAmount: number;
+    description: string | null;
+}
+export interface DraftEntryView {
+    entryId: string;
+    postingDate: string;
+    type: string;
+    memo: string | null;
+    provenance: string | null;
+    sourceStructureId: string | null;
+    sourceStructureName: string | null;
+    lineItems: DraftLineItemView[];
+    totalDebit: number;
+    totalCredit: number;
+    balanced: boolean;
+}
+export interface PeriodDraftsView {
+    period: string;
+    periodStart: string;
+    periodEnd: string;
+    draftCount: number;
+    totalDebit: number;
+    totalCredit: number;
+    allBalanced: boolean;
+    drafts: DraftEntryView[];
+}
+export interface ManualClosingLineItem {
+    elementId: string;
+    debitAmount?: number;
+    creditAmount?: number;
+    description?: string | null;
+}
+export interface CreateManualClosingEntryOptions {
     postingDate: string;
     memo: string;
-    debitElementId: string;
-    creditElementId: string;
-    amount: number;
+    lineItems: ManualClosingLineItem[];
+    entryType?: LedgerEntryType;
+}
+export interface TruncateScheduleOptions {
+    newEndDate: string;
+    reason: string;
+}
+export interface TruncateScheduleResult {
+    structureId: string;
+    newEndDate: string;
+    factsDeleted: number;
+    reason: string;
 }
 export interface CreateScheduleOptions {
     name: string;
@@ -85,7 +199,7 @@ export interface CreateScheduleOptions {
     entryTemplate: {
         debitElementId: string;
         creditElementId: string;
-        entryType?: string;
+        entryType?: LedgerEntryType;
         memoTemplate?: string;
     };
     taxonomyId?: string;
@@ -221,7 +335,14 @@ export declare class LedgerClient {
      */
     getPeriodCloseStatus(graphId: string, periodStart: string, periodEnd: string): Promise<PeriodCloseStatus>;
     /**
-     * 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
      */
     createClosingEntry(graphId: string, structureId: string, postingDate: string, periodStart: string, periodEnd: string, memo?: string): Promise<ClosingEntry>;
     /**
@@ -239,4 +360,57 @@ export declare class LedgerClient {
         startDate?: string;
         endDate?: string;
     }): Promise<AccountRollupsResponse>;
+    /**
+     * 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.
+     */
+    initializeLedger(graphId: string, options?: InitializeLedgerOptions): Promise<InitializeLedgerResult>;
+    /**
+     * Get the current fiscal calendar state — pointers, gap, closeable status.
+     */
+    getFiscalCalendar(graphId: string): Promise<FiscalCalendarState>;
+    /**
+     * Set the close target for a graph. Validates that the target is not in
+     * the future and not before `closed_through`.
+     */
+    setCloseTarget(graphId: string, period: string, note?: string | null): Promise<FiscalCalendarState>;
+    /**
+     * 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).
+     */
+    closePeriod(graphId: string, period: string, options?: ClosePeriodOptions): Promise<ClosePeriodResult>;
+    /**
+     * 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.
+     */
+    reopenPeriod(graphId: string, period: string, reason: string, note?: string | null): Promise<FiscalCalendarState>;
+    /**
+     * 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.
+     */
+    listPeriodDrafts(graphId: string, period: string): Promise<PeriodDraftsView>;
+    /**
+     * 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).
+     */
+    truncateSchedule(graphId: string, structureId: string, options: TruncateScheduleOptions): Promise<TruncateScheduleResult>;
+    /**
+     * 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.
+     */
+    createManualClosingEntry(graphId: string, options: CreateManualClosingEntryOptions): Promise<ClosingEntry>;
 }

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,7 @@ class LedgerClient {
             throw new Error(`Create closing entry 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,
-        };
+        return toClosingEntry(data);
     }
     // ── Closing Book ─────────────────────────────────────────────────────
     /**
@@ -492,5 +491,247 @@ class LedgerClient {
         }
         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 {
+            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,
+        })),
+    };
+}