@robosystems/client 0.2.48 → 0.3.0

package/extensions/LedgerClient.js

@@ -2,324 +2,192 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LedgerClient = void 0;
-/**
- * Ledger Client for RoboSystems API
- *
- * High-level client for all ledger concerns: chart of accounts, transactions,
- * trial balance, taxonomy, mappings, and AI auto-mapping. This is the
- * operational backbone — reports consume these as inputs.
- */
+const graphql_request_1 = require("graphql-request");
 const sdk_gen_1 = require("../sdk.gen");
-// ── Client ──────────────────────────────────────────────────────────────
+const client_1 = require("./graphql/client");
+const graphql_1 = require("./graphql/generated/graphql");
 class LedgerClient {
     constructor(config) {
         this.config = config;
+        this.gql = new client_1.GraphQLClientCache(config);
     }
     // ── Entity ──────────────────────────────────────────────────────────
     /**
      * Get the entity (company/organization) for this graph.
+     * Returns null when the ledger has no entity yet.
      */
     async getEntity(graphId) {
-        const response = await (0, sdk_gen_1.getLedgerEntity)({
-            path: { graph_id: graphId },
-        });
-        if (response.response.status === 404)
-            return null;
-        if (response.error) {
-            throw new Error(`Get entity failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return {
-            id: data.id,
-            name: data.name,
-            legalName: data.legal_name ?? null,
-            entityType: data.entity_type ?? null,
-            industry: data.industry ?? null,
-            status: data.status ?? null,
-        };
+        return this.gqlQuery(graphId, graphql_1.GetLedgerEntityDocument, undefined, 'Get entity', (data) => data.entity);
+    }
+    /** List all entities for this graph, optionally filtered by source system. */
+    async listEntities(graphId, options) {
+        return this.gqlQuery(graphId, graphql_1.ListLedgerEntitiesDocument, { source: options?.source ?? null }, 'List entities', (data) => data.entities);
     }
-    // ── Accounts (Chart of Accounts) ───────────────────────────────────
     /**
-     * List accounts (flat).
+     * Update the entity for this graph. Only non-null fields are applied.
+     * Returns the updated entity.
      */
-    async listAccounts(graphId) {
-        const response = await (0, sdk_gen_1.listLedgerAccounts)({
+    async updateEntity(graphId, updates) {
+        const envelope = await this.callOperation('Update entity', (0, sdk_gen_1.opUpdateEntity)({
             path: { graph_id: graphId },
-        });
-        if (response.error) {
-            throw new Error(`List accounts failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+            body: updates,
+        }));
+        return envelope.result;
     }
-    /**
-     * Get the account tree (hierarchical).
-     */
+    // ── Summary ────────────────────────────────────────────────────────
+    /** Ledger rollup counts + QB sync metadata. */
+    async getSummary(graphId) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerSummaryDocument, undefined, 'Get summary', (data) => data.summary);
+    }
+    // ── Accounts (Chart of Accounts) ───────────────────────────────────
+    /** List CoA accounts with optional filters and pagination. */
+    async listAccounts(graphId, options) {
+        return this.gqlQuery(graphId, graphql_1.ListLedgerAccountsDocument, {
+            classification: options?.classification ?? null,
+            isActive: options?.isActive ?? null,
+            limit: options?.limit ?? 100,
+            offset: options?.offset ?? 0,
+        }, 'List accounts', (data) => data.accounts);
+    }
+    /** Hierarchical Chart of Accounts (up to 4 levels deep). */
     async getAccountTree(graphId) {
-        const response = await (0, sdk_gen_1.getLedgerAccountTree)({
-            path: { graph_id: graphId },
-        });
-        if (response.error) {
-            throw new Error(`Get account tree failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+        return this.gqlQuery(graphId, graphql_1.GetLedgerAccountTreeDocument, undefined, 'Get account tree', (data) => data.accountTree);
+    }
+    /** Accounts rolled up to reporting concepts via a mapping structure. */
+    async getAccountRollups(graphId, options) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerAccountRollupsDocument, {
+            mappingId: options?.mappingId ?? null,
+            startDate: options?.startDate ?? null,
+            endDate: options?.endDate ?? null,
+        }, 'Get account rollups', (data) => data.accountRollups);
     }
     // ── Transactions ────────────────────────────────────────────────────
-    /**
-     * List transactions with optional date filters.
-     */
+    /** List transactions with optional type + date filters and pagination. */
     async listTransactions(graphId, options) {
-        const response = await (0, sdk_gen_1.listLedgerTransactions)({
-            path: { graph_id: graphId },
-            query: {
-                start_date: options?.startDate,
-                end_date: options?.endDate,
-                limit: options?.limit,
-                offset: options?.offset,
-            },
-        });
-        if (response.error) {
-            throw new Error(`List transactions failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+        return this.gqlQuery(graphId, graphql_1.ListLedgerTransactionsDocument, {
+            type: options?.type ?? null,
+            startDate: options?.startDate ?? null,
+            endDate: options?.endDate ?? null,
+            limit: options?.limit ?? 100,
+            offset: options?.offset ?? 0,
+        }, 'List transactions', (data) => data.transactions);
     }
-    /**
-     * Get transaction detail with entries and line items.
-     */
+    /** Get transaction detail with entries + line items. */
     async getTransaction(graphId, transactionId) {
-        const response = await (0, sdk_gen_1.getLedgerTransaction)({
-            path: { graph_id: graphId, transaction_id: transactionId },
-        });
-        if (response.error) {
-            throw new Error(`Get transaction failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+        return this.gqlQuery(graphId, graphql_1.GetLedgerTransactionDocument, { transactionId }, 'Get transaction', (data) => data.transaction);
     }
     // ── Trial Balance ──────────────────────────────────────────────────
-    /**
-     * Get trial balance (CoA-level debits/credits).
-     */
+    /** Trial balance by raw CoA account. */
     async getTrialBalance(graphId, options) {
-        const response = await (0, sdk_gen_1.getLedgerTrialBalance)({
-            path: { graph_id: graphId },
-            query: {
-                start_date: options?.startDate,
-                end_date: options?.endDate,
-            },
-        });
-        if (response.error) {
-            throw new Error(`Get trial balance failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
-    }
-    /**
-     * Get mapped trial balance (CoA rolled up to GAAP concepts).
-     */
-    async getMappedTrialBalance(graphId, options) {
-        const response = await (0, sdk_gen_1.getMappedTrialBalance)({
-            path: { graph_id: graphId },
-            query: {
-                mapping_id: options?.mappingId,
-                start_date: options?.startDate,
-                end_date: options?.endDate,
-            },
-        });
-        if (response.error) {
-            throw new Error(`Get mapped trial balance failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+        return this.gqlQuery(graphId, graphql_1.GetLedgerTrialBalanceDocument, {
+            startDate: options?.startDate ?? null,
+            endDate: options?.endDate ?? null,
+        }, 'Get trial balance', (data) => data.trialBalance);
     }
-    // ── Summary ────────────────────────────────────────────────────────
-    /**
-     * Get ledger summary (account count, transaction count, date range).
-     */
-    async getSummary(graphId) {
-        const response = await (0, sdk_gen_1.getLedgerSummary)({
-            path: { graph_id: graphId },
-        });
-        if (response.error) {
-            throw new Error(`Get summary failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+    /** Trial balance rolled up to GAAP reporting concepts via a mapping. */
+    async getMappedTrialBalance(graphId, mappingId, options) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerMappedTrialBalanceDocument, {
+            mappingId,
+            startDate: options?.startDate ?? null,
+            endDate: options?.endDate ?? null,
+        }, 'Get mapped trial balance', (data) => data.mappedTrialBalance);
     }
     // ── Taxonomy ────────────────────────────────────────────────────────
-    /**
-     * Get the reporting taxonomy (US GAAP seed).
-     */
+    /** Get the locked US GAAP reporting taxonomy for this graph. */
     async getReportingTaxonomy(graphId) {
-        const response = await (0, sdk_gen_1.getReportingTaxonomy)({
-            path: { graph_id: graphId },
-        });
-        if (response.error) {
-            throw new Error(`Get reporting taxonomy failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+        return this.gqlQuery(graphId, graphql_1.GetLedgerReportingTaxonomyDocument, undefined, 'Get reporting taxonomy', (data) => data.reportingTaxonomy);
     }
-    /**
-     * List reporting structures (IS, BS, CF) for a taxonomy.
-     */
-    async listStructures(graphId, taxonomyId) {
-        const response = await (0, sdk_gen_1.listStructures)({
-            path: { graph_id: graphId },
-            query: taxonomyId ? { taxonomy_id: taxonomyId } : undefined,
-        });
-        if (response.error) {
-            throw new Error(`List structures failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return (data.structures ?? []).map((s) => ({
-            id: s.id,
-            name: s.name,
-            structureType: s.structure_type,
-        }));
+    /** List active taxonomies with optional type filter. */
+    async listTaxonomies(graphId, options) {
+        const list = await this.gqlQuery(graphId, graphql_1.ListLedgerTaxonomiesDocument, { taxonomyType: options?.taxonomyType ?? null }, 'List taxonomies', (data) => data.taxonomies);
+        return list?.taxonomies ?? [];
     }
-    /**
-     * List elements (CoA accounts, GAAP concepts, etc.).
-     */
+    /** Create a new taxonomy (used for CoA + mapping taxonomies). */
+    async createTaxonomy(graphId, body) {
+        const envelope = await this.callOperation('Create taxonomy', (0, sdk_gen_1.opCreateTaxonomy)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    /** List elements (CoA accounts, GAAP concepts, etc.) with filters. */
     async listElements(graphId, options) {
-        const response = await (0, sdk_gen_1.listElements)({
-            path: { graph_id: graphId },
-            query: {
-                taxonomy_id: options?.taxonomyId,
-                source: options?.source,
-                classification: options?.classification,
-                is_abstract: options?.isAbstract,
-                limit: options?.limit,
-                offset: options?.offset,
-            },
-        });
-        if (response.error) {
-            throw new Error(`List elements failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+        return this.gqlQuery(graphId, graphql_1.ListLedgerElementsDocument, {
+            taxonomyId: options?.taxonomyId ?? null,
+            source: options?.source ?? null,
+            classification: options?.classification ?? null,
+            isAbstract: options?.isAbstract ?? null,
+            limit: options?.limit ?? 100,
+            offset: options?.offset ?? 0,
+        }, 'List elements', (data) => data.elements);
     }
-    // ── Mappings ────────────────────────────────────────────────────────
-    /**
-     * Create a new CoA→GAAP mapping structure.
-     * Returns the created mapping info.
-     */
-    async createMappingStructure(graphId, options) {
-        const response = await (0, sdk_gen_1.createStructure)({
-            path: { graph_id: graphId },
-            body: {
-                name: options?.name ?? 'CoA to Reporting',
-                description: options?.description ?? 'Map Chart of Accounts to US GAAP reporting concepts',
-                structure_type: 'coa_mapping',
-                taxonomy_id: options?.taxonomyId ?? 'tax_usgaap_reporting',
-            },
-        });
-        if (response.error) {
-            throw new Error(`Create mapping structure failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return {
-            id: data.id,
-            name: data.name,
-            description: data.description ?? null,
-            structureType: data.structure_type,
-            taxonomyId: data.taxonomy_id,
-            isActive: data.is_active ?? true,
-        };
+    /** CoA elements not yet mapped to a reporting concept. */
+    async listUnmappedElements(graphId, options) {
+        return this.gqlQuery(graphId, graphql_1.ListLedgerUnmappedElementsDocument, { mappingId: options?.mappingId ?? null }, 'List unmapped elements', (data) => data.unmappedElements);
+    }
+    // ── Structures ──────────────────────────────────────────────────────
+    /** List reporting structures (IS, BS, CF, schedules) with optional filters. */
+    async listStructures(graphId, options) {
+        const list = await this.gqlQuery(graphId, graphql_1.ListLedgerStructuresDocument, {
+            taxonomyId: options?.taxonomyId ?? null,
+            structureType: options?.structureType ?? null,
+        }, 'List structures', (data) => data.structures);
+        return list?.structures ?? [];
     }
     /**
-     * List available CoA→GAAP mapping structures.
+     * Create a new structure. Most common use is a CoA→reporting mapping
+     * structure; also used for custom statement + schedule structures.
      */
+    async createStructure(graphId, body) {
+        const envelope = await this.callOperation('Create structure', (0, sdk_gen_1.opCreateStructure)({ path: { graph_id: graphId }, body }));
+        return envelope.result;
+    }
+    // ── Mappings ────────────────────────────────────────────────────────
+    /** List active CoA→reporting mapping structures. */
     async listMappings(graphId) {
-        const response = await (0, sdk_gen_1.listMappings)({
-            path: { graph_id: graphId },
-        });
-        if (response.error) {
-            throw new Error(`List mappings failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return (data.structures ?? []).map((s) => ({
-            id: s.id,
-            name: s.name,
-            description: s.description ?? null,
-            structureType: s.structure_type,
-            taxonomyId: s.taxonomy_id,
-            isActive: s.is_active ?? true,
-        }));
+        const list = await this.gqlQuery(graphId, graphql_1.ListLedgerMappingsDocument, undefined, 'List mappings', (data) => data.mappings);
+        return list?.structures ?? [];
     }
-    /**
-     * Get mapping detail — all associations with element names.
-     */
-    async getMappingDetail(graphId, mappingId) {
-        const response = await (0, sdk_gen_1.getMappingDetail)({
-            path: { graph_id: graphId, mapping_id: mappingId },
-        });
-        if (response.error) {
-            throw new Error(`Get mapping detail failed: ${JSON.stringify(response.error)}`);
-        }
-        return response.data;
+    /** Get a mapping structure with all its associations. */
+    async getMapping(graphId, mappingId) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerMappingDocument, { mappingId }, 'Get mapping', (data) => data.mapping);
     }
-    /**
-     * Get mapping coverage — how many CoA elements are mapped.
-     */
+    /** Mapping coverage stats — how many CoA elements are mapped. */
     async getMappingCoverage(graphId, mappingId) {
-        const response = await (0, sdk_gen_1.getMappingCoverage)({
-            path: { graph_id: graphId, mapping_id: mappingId },
-        });
-        if (response.error) {
-            throw new Error(`Get mapping coverage failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return {
-            totalCoaElements: data.total_coa_elements ?? 0,
-            mappedCount: data.mapped_count ?? 0,
-            unmappedCount: data.unmapped_count ?? 0,
-            coveragePercent: data.coverage_percent ?? 0,
-            highConfidence: data.high_confidence ?? 0,
-            mediumConfidence: data.medium_confidence ?? 0,
-            lowConfidence: data.low_confidence ?? 0,
-        };
+        return this.gqlQuery(graphId, graphql_1.GetLedgerMappingCoverageDocument, { mappingId }, 'Get mapping coverage', (data) => data.mappingCoverage);
     }
-    /**
-     * Create a manual mapping association (CoA element → GAAP element).
-     */
-    async createMapping(graphId, mappingId, fromElementId, toElementId, confidence) {
-        const response = await (0, sdk_gen_1.createMappingAssociation)({
-            path: { graph_id: graphId, mapping_id: mappingId },
-            body: {
-                from_element_id: fromElementId,
-                to_element_id: toElementId,
-                confidence: confidence ?? 1.0,
-            },
-        });
-        if (response.error) {
-            throw new Error(`Create mapping failed: ${JSON.stringify(response.error)}`);
-        }
+    /** Create a manual mapping association between two elements. */
+    async createMappingAssociation(graphId, body) {
+        const envelope = await this.callOperation('Create mapping association', (0, sdk_gen_1.opCreateMappingAssociation)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
     }
-    /**
-     * Delete a mapping association.
-     */
-    async deleteMapping(graphId, mappingId, associationId) {
-        const response = await (0, sdk_gen_1.deleteMappingAssociation)({
-            path: { graph_id: graphId, mapping_id: mappingId, association_id: associationId },
-        });
-        if (response.error) {
-            throw new Error(`Delete mapping failed: ${JSON.stringify(response.error)}`);
-        }
+    /** Delete a mapping association. */
+    async deleteMappingAssociation(graphId, body) {
+        const envelope = await this.callOperation('Delete mapping association', (0, sdk_gen_1.opDeleteMappingAssociation)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? { deleted: true });
     }
     /**
-     * Trigger AI auto-mapping (MappingAgent).
-     * Returns immediately — the agent runs in the background.
+     * Trigger the AI MappingAgent. Returns the operation id — async; the
+     * agent runs in the background. Consumers can subscribe to progress
+     * via `/v1/operations/{operationId}/stream`.
      */
-    async autoMap(graphId, mappingId) {
-        const response = await (0, sdk_gen_1.autoMapElements)({
-            path: { graph_id: graphId, mapping_id: mappingId },
-        });
-        if (response.error) {
-            throw new Error(`Auto-map failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return {
-            operationId: data?.operation_id,
-        };
+    async autoMapElements(graphId, body) {
+        const envelope = await this.callOperation('Auto-map elements', (0, sdk_gen_1.opAutoMapElements)({ path: { graph_id: graphId }, body }));
+        return { operationId: envelope.operationId, status: envelope.status };
     }
     // ── Schedules ──────────────────────────────────────────────────────
-    /**
-     * Create a schedule with pre-generated monthly facts.
-     */
+    /** List all schedule structures with metadata. */
+    async listSchedules(graphId) {
+        const list = await this.gqlQuery(graphId, graphql_1.ListLedgerSchedulesDocument, undefined, 'List schedules', (data) => data.schedules);
+        return list?.schedules ?? [];
+    }
+    /** Schedule facts optionally filtered by period window. */
+    async getScheduleFacts(graphId, structureId, options) {
+        const facts = await this.gqlQuery(graphId, graphql_1.GetLedgerScheduleFactsDocument, {
+            structureId,
+            periodStart: options?.periodStart ?? null,
+            periodEnd: options?.periodEnd ?? null,
+        }, 'Get schedule facts', (data) => data.scheduleFacts);
+        return facts?.facts ?? [];
+    }
+    /** Create a new schedule with pre-generated monthly facts. */
     async createSchedule(graphId, options) {
         const body = {
             name: options.name,
@@ -344,153 +212,207 @@ class LedgerClient {
                 }
                 : undefined,
         };
-        const response = await (0, sdk_gen_1.createSchedule)({
-            path: { graph_id: graphId },
-            body,
-        });
-        if (response.error) {
-            throw new Error(`Create schedule failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
+        const envelope = await this.callOperation('Create schedule', (0, sdk_gen_1.opCreateSchedule)({ path: { graph_id: graphId }, body }));
+        const raw = envelope.result;
         return {
-            structureId: data.structure_id,
-            name: data.name,
-            taxonomyId: data.taxonomy_id,
-            totalPeriods: data.total_periods,
-            totalFacts: data.total_facts,
+            structureId: raw.structure_id,
+            name: raw.name,
+            taxonomyId: raw.taxonomy_id,
+            totalPeriods: raw.total_periods,
+            totalFacts: raw.total_facts,
         };
     }
-    /**
-     * List all schedules for a graph.
-     */
-    async listSchedules(graphId) {
-        const response = await (0, sdk_gen_1.listSchedules)({
-            path: { graph_id: graphId },
-        });
-        if (response.error) {
-            throw new Error(`List schedules failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return (data.schedules ?? []).map((s) => ({
-            structureId: s.structure_id,
-            name: s.name,
-            taxonomyName: s.taxonomy_name,
-            entryTemplate: s.entry_template ?? null,
-            scheduleMetadata: s.schedule_metadata ?? null,
-            totalPeriods: s.total_periods,
-            periodsWithEntries: s.periods_with_entries,
-        }));
-    }
-    /**
-     * Get facts for a schedule, optionally filtered by period.
-     */
-    async getScheduleFacts(graphId, structureId, periodStart, periodEnd) {
-        const response = await (0, sdk_gen_1.getScheduleFacts)({
-            path: { graph_id: graphId, structure_id: structureId },
-            query: {
-                period_start: periodStart ?? null,
-                period_end: periodEnd ?? null,
-            },
-        });
-        if (response.error) {
-            throw new Error(`Get schedule facts failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
-        return (data.facts ?? []).map((f) => ({
-            elementId: f.element_id,
-            elementName: f.element_name,
-            value: f.value,
-            periodStart: f.period_start,
-            periodEnd: f.period_end,
-        }));
-    }
-    /**
-     * Get close status for all schedules in a fiscal period.
-     */
-    async getPeriodCloseStatus(graphId, periodStart, periodEnd) {
-        const response = await (0, sdk_gen_1.getPeriodCloseStatus)({
-            path: { graph_id: graphId },
-            query: { period_start: periodStart, period_end: periodEnd },
-        });
-        if (response.error) {
-            throw new Error(`Get period close status failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
+    /** Truncate a schedule — end it early at `newEndDate`. */
+    async truncateSchedule(graphId, structureId, options) {
+        const body = {
+            structure_id: structureId,
+            new_end_date: options.newEndDate,
+            reason: options.reason,
+        };
+        const envelope = await this.callOperation('Truncate schedule', (0, sdk_gen_1.opTruncateSchedule)({ path: { graph_id: graphId }, body }));
+        const raw = envelope.result;
         return {
-            fiscalPeriodStart: data.fiscal_period_start,
-            fiscalPeriodEnd: data.fiscal_period_end,
-            periodStatus: data.period_status,
-            schedules: (data.schedules ?? []).map((s) => ({
-                structureId: s.structure_id,
-                structureName: s.structure_name,
-                amount: s.amount,
-                status: s.status,
-                entryId: s.entry_id ?? null,
-            })),
-            totalDraft: data.total_draft,
-            totalPosted: data.total_posted,
+            structureId: raw.structure_id,
+            newEndDate: raw.new_end_date,
+            factsDeleted: raw.facts_deleted,
+            reason: raw.reason,
         };
     }
+    // ── Period close ────────────────────────────────────────────────────
+    /** Close status for all schedules in a fiscal period. */
+    async getPeriodCloseStatus(graphId, periodStart, periodEnd) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerPeriodCloseStatusDocument, { periodStart, periodEnd }, 'Get period close status', (data) => data.periodCloseStatus);
+    }
+    /** All draft entries in a period, fully expanded for review pre-close. */
+    async listPeriodDrafts(graphId, period) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerPeriodDraftsDocument, { period }, 'List period drafts', (data) => data.periodDrafts);
+    }
     /**
-     * Create a draft closing entry from a schedule's facts for a period.
+     * Idempotently create (or refresh) a draft closing entry from a
+     * schedule for a period. See `ClosingEntryOutcome` for semantics.
      */
     async createClosingEntry(graphId, structureId, postingDate, periodStart, periodEnd, memo) {
         const body = {
+            structure_id: structureId,
             posting_date: postingDate,
             period_start: periodStart,
             period_end: periodEnd,
             memo: memo ?? undefined,
         };
-        const response = await (0, sdk_gen_1.createClosingEntry)({
-            path: { graph_id: graphId, structure_id: structureId },
-            body,
-        });
-        if (response.error) {
-            throw new Error(`Create closing entry failed: ${JSON.stringify(response.error)}`);
-        }
-        const data = response.data;
+        const envelope = await this.callOperation('Create closing entry', (0, sdk_gen_1.opCreateClosingEntry)({ path: { graph_id: graphId }, body }));
+        return rawToClosingEntry(envelope.result);
+    }
+    /**
+     * Create a manual balanced closing entry (not tied to a schedule).
+     * Used for disposals, adjustments, and one-off closing events.
+     */
+    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 envelope = await this.callOperation('Create manual closing entry', (0, sdk_gen_1.opCreateManualClosingEntry)({ path: { graph_id: graphId }, body }));
+        return rawToClosingEntry(envelope.result);
+    }
+    // ── Closing book ───────────────────────────────────────────────────
+    /** Grouped closing book structures for the close-screen sidebar. */
+    async getClosingBookStructures(graphId) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerClosingBookStructuresDocument, undefined, 'Get closing book structures', (data) => data.closingBookStructures);
+    }
+    // ── Fiscal Calendar ────────────────────────────────────────────────
+    /** Current fiscal calendar state — pointers, gap, closeable status. */
+    async getFiscalCalendar(graphId) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerFiscalCalendarDocument, undefined, 'Get fiscal calendar', (data) => data.fiscalCalendar);
+    }
+    /** One-time ledger initialization — seed fiscal calendar + periods. */
+    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 envelope = await this.callOperation('Initialize ledger', (0, sdk_gen_1.opInitializeLedger)({ path: { graph_id: graphId }, body }));
+        const raw = envelope.result;
+        return {
+            fiscalCalendar: rawFiscalCalendarToCamel(raw.fiscal_calendar),
+            periodsCreated: raw.periods_created ?? 0,
+            warnings: raw.warnings ?? [],
+        };
+    }
+    /** Set the user-controlled close target (YYYY-MM). */
+    async setCloseTarget(graphId, period, note) {
+        const body = { period, note: note ?? null };
+        const envelope = await this.callOperation('Set close target', (0, sdk_gen_1.opSetCloseTarget)({ path: { graph_id: graphId }, body }));
+        return rawFiscalCalendarToCamel(envelope.result);
+    }
+    /** Close a fiscal period — the final commit action. */
+    async closePeriod(graphId, period, options) {
+        const body = {
+            period,
+            note: options?.note ?? null,
+            allow_stale_sync: options?.allowStaleSync,
+        };
+        const envelope = await this.callOperation('Close period', (0, sdk_gen_1.opClosePeriod)({ path: { graph_id: graphId }, body }));
+        const raw = envelope.result;
         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,
+            period: raw.period,
+            entriesPosted: raw.entries_posted ?? 0,
+            targetAutoAdvanced: raw.target_auto_advanced ?? false,
+            fiscalCalendar: rawFiscalCalendarToCamel(raw.fiscal_calendar),
+        };
+    }
+    /** Reopen a closed fiscal period. Requires a reason for the audit log. */
+    async reopenPeriod(graphId, period, reason, note) {
+        const body = {
+            period,
+            reason,
+            note: note ?? null,
         };
+        const envelope = await this.callOperation('Reopen period', (0, sdk_gen_1.opReopenPeriod)({ path: { graph_id: graphId }, body }));
+        return rawFiscalCalendarToCamel(envelope.result);
     }
-    // ── Closing Book ─────────────────────────────────────────────────────
+    // Reports, statements, and publish lists live on `ReportClient`.
+    // ── Internal helpers ────────────────────────────────────────────────
     /**
-     * Get all closing book structure categories for the sidebar.
-     * Returns statements, account rollups, schedules, trial balance,
-     * and period close grouped into categories.
+     * Run a typed GraphQL query against the per-graph endpoint and
+     * translate ClientError into a readable facade error.
      */
-    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)}`);
+    async gqlQuery(graphId, document, variables, label, pick) {
+        try {
+            const client = this.gql.get(graphId);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const raw = client.request;
+            // graphql-request's overloads don't cleanly resolve for generic
+            // helpers wrapping codegen's `Exact<>` var types, so we bypass
+            // the typed overload with a narrow cast of `request` itself.
+            const data = (await raw.call(client, document, variables));
+            return pick(data);
+        }
+        catch (err) {
+            if (err instanceof graphql_request_1.ClientError) {
+                throw new Error(`${label} failed: ${JSON.stringify(err.response.errors ?? err.message)}`);
+            }
+            throw err;
         }
-        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.
+     * Await an SDK-generated `opXxx(...)` call, throw a readable error on
+     * non-2xx, and return the `OperationEnvelope` on success.
      */
-    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)}`);
+    async callOperation(label, call) {
+        const response = await call;
+        if (response.error !== undefined) {
+            throw new Error(`${label} failed: ${JSON.stringify(response.error)}`);
+        }
+        if (response.data === undefined) {
+            throw new Error(`${label} failed: empty response`);
         }
         return response.data;
     }
 }
 exports.LedgerClient = LedgerClient;
+// ── Module-private conversion helpers ─────────────────────────────────
+function rawToClosingEntry(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 rawFiscalCalendarToCamel(raw) {
+    return {
+        graphId: raw.graph_id,
+        fiscalYearStartMonth: raw.fiscal_year_start_month,
+        closedThrough: raw.closed_through ?? null,
+        closeTarget: raw.close_target ?? null,
+        gapPeriods: raw.gap_periods ?? 0,
+        catchUpSequence: raw.catch_up_sequence ?? [],
+        closeableNow: raw.closeable_now ?? false,
+        blockers: raw.blockers ?? [],
+        lastCloseAt: raw.last_close_at ?? null,
+        initializedAt: raw.initialized_at ?? null,
+        lastSyncAt: raw.last_sync_at ?? null,
+        periods: (raw.periods ?? []).map((p) => ({
+            name: p.name,
+            startDate: p.start_date,
+            endDate: p.end_date,
+            status: p.status,
+            closedAt: p.closed_at ?? null,
+        })),
+    };
+}