@robosystems/client 0.2.48 → 0.3.0

package/extensions/LedgerClient.d.ts

@@ -1,42 +1,63 @@
-import type { AccountListResponse, AccountRollupsResponse, AccountTreeResponse, ClosingBookStructuresResponse, LedgerSummaryResponse, LedgerTransactionDetailResponse, LedgerTransactionListResponse, MappingDetailResponse, TrialBalanceResponse } from '../types.gen';
-export interface LedgerEntity {
-    id: string;
-    name: string;
-    legalName: string | null;
-    entityType: string | null;
-    industry: string | null;
-    status: string | null;
-}
-export interface MappingInfo {
-    id: string;
-    name: string;
-    description: string | null;
-    structureType: string;
-    taxonomyId: string;
-    isActive: boolean;
+import type { AutoMapElementsOperation, CreateMappingAssociationOperation, CreateStructureRequest, CreateTaxonomyRequest, DeleteMappingAssociationOperation, OperationEnvelope, UpdateEntityRequest } from '../types.gen';
+import { type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, type GetLedgerFiscalCalendarQuery, type GetLedgerMappedTrialBalanceQuery, type GetLedgerMappingCoverageQuery, type GetLedgerMappingQuery, type GetLedgerPeriodCloseStatusQuery, type GetLedgerPeriodDraftsQuery, type GetLedgerReportingTaxonomyQuery, type GetLedgerScheduleFactsQuery, type GetLedgerSummaryQuery, type GetLedgerTransactionQuery, type GetLedgerTrialBalanceQuery, type ListLedgerAccountsQuery, type ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerMappingsQuery, type ListLedgerSchedulesQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery } from './graphql/generated/graphql';
+export type LedgerEntity = NonNullable<GetLedgerEntityQuery['entity']>;
+export type LedgerEntitySummary = ListLedgerEntitiesQuery['entities'][number];
+export type LedgerSummary = NonNullable<GetLedgerSummaryQuery['summary']>;
+export type LedgerAccountList = NonNullable<ListLedgerAccountsQuery['accounts']>;
+export type LedgerAccount = LedgerAccountList['accounts'][number];
+export type LedgerAccountTree = NonNullable<GetLedgerAccountTreeQuery['accountTree']>;
+export type LedgerAccountRollups = NonNullable<GetLedgerAccountRollupsQuery['accountRollups']>;
+export type LedgerTrialBalance = NonNullable<GetLedgerTrialBalanceQuery['trialBalance']>;
+export type LedgerMappedTrialBalance = NonNullable<GetLedgerMappedTrialBalanceQuery['mappedTrialBalance']>;
+export type LedgerTransactionList = NonNullable<ListLedgerTransactionsQuery['transactions']>;
+export type LedgerTransactionListItem = LedgerTransactionList['transactions'][number];
+export type LedgerTransaction = NonNullable<GetLedgerTransactionQuery['transaction']>;
+export type LedgerReportingTaxonomy = NonNullable<GetLedgerReportingTaxonomyQuery['reportingTaxonomy']>;
+export type LedgerTaxonomyList = NonNullable<ListLedgerTaxonomiesQuery['taxonomies']>;
+export type LedgerTaxonomy = LedgerTaxonomyList['taxonomies'][number];
+export type LedgerElementList = NonNullable<ListLedgerElementsQuery['elements']>;
+export type LedgerElement = LedgerElementList['elements'][number];
+export type LedgerUnmappedElement = ListLedgerUnmappedElementsQuery['unmappedElements'][number];
+export type LedgerStructureList = NonNullable<ListLedgerStructuresQuery['structures']>;
+export type LedgerStructure = LedgerStructureList['structures'][number];
+export type LedgerMappingList = NonNullable<ListLedgerMappingsQuery['mappings']>;
+export type LedgerMappingInfo = LedgerMappingList['structures'][number];
+export type LedgerMapping = NonNullable<GetLedgerMappingQuery['mapping']>;
+export type LedgerMappingCoverage = NonNullable<GetLedgerMappingCoverageQuery['mappingCoverage']>;
+export type LedgerScheduleList = NonNullable<ListLedgerSchedulesQuery['schedules']>;
+export type LedgerSchedule = LedgerScheduleList['schedules'][number];
+export type LedgerScheduleFacts = NonNullable<GetLedgerScheduleFactsQuery['scheduleFacts']>;
+export type LedgerScheduleFact = LedgerScheduleFacts['facts'][number];
+export type LedgerPeriodCloseStatus = NonNullable<GetLedgerPeriodCloseStatusQuery['periodCloseStatus']>;
+export type LedgerPeriodCloseItem = LedgerPeriodCloseStatus['schedules'][number];
+export type LedgerPeriodDrafts = NonNullable<GetLedgerPeriodDraftsQuery['periodDrafts']>;
+export type LedgerDraftEntry = LedgerPeriodDrafts['drafts'][number];
+export type LedgerDraftLineItem = LedgerDraftEntry['lineItems'][number];
+export type LedgerClosingBookStructures = NonNullable<GetLedgerClosingBookStructuresQuery['closingBookStructures']>;
+export type LedgerFiscalCalendar = NonNullable<GetLedgerFiscalCalendarQuery['fiscalCalendar']>;
+export type LedgerFiscalPeriod = LedgerFiscalCalendar['periods'][number];
+export interface InitializeLedgerResult {
+    fiscalCalendar: LedgerFiscalCalendar;
+    periodsCreated: number;
+    warnings: string[];
 }
-export interface MappingCoverage {
-    totalCoaElements: number;
-    mappedCount: number;
-    unmappedCount: number;
-    coveragePercent: number;
-    highConfidence: number;
-    mediumConfidence: number;
-    lowConfidence: number;
+export interface ClosePeriodResult {
+    period: string;
+    entriesPosted: number;
+    targetAutoAdvanced: boolean;
+    fiscalCalendar: LedgerFiscalCalendar;
 }
-export interface Structure {
-    id: string;
-    name: string;
-    structureType: string;
-}
-export interface Schedule {
-    structureId: string;
-    name: string;
-    taxonomyName: string;
-    entryTemplate: Record<string, unknown> | null;
-    scheduleMetadata: Record<string, unknown> | null;
-    totalPeriods: number;
-    periodsWithEntries: number;
+export type ClosingEntryOutcome = 'created' | 'unchanged' | 'regenerated' | 'removed' | 'skipped';
+export interface ClosingEntry {
+    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 interface ScheduleCreated {
     structureId: string;
@@ -45,36 +66,39 @@ export interface ScheduleCreated {
     totalPeriods: number;
     totalFacts: number;
 }
-export interface ScheduleFact {
-    elementId: string;
-    elementName: string;
-    value: number;
-    periodStart: string;
-    periodEnd: string;
-}
-export interface PeriodCloseItem {
+export interface TruncateScheduleResult {
     structureId: string;
-    structureName: string;
-    amount: number;
-    status: string;
-    entryId: string | null;
+    newEndDate: string;
+    factsDeleted: number;
+    reason: string;
 }
-export interface PeriodCloseStatus {
-    fiscalPeriodStart: string;
-    fiscalPeriodEnd: string;
-    periodStatus: string;
-    schedules: PeriodCloseItem[];
-    totalDraft: number;
-    totalPosted: number;
+export type LedgerEntryType = 'standard' | 'adjusting' | 'closing' | 'reversing';
+export interface InitializeLedgerOptions {
+    closedThrough?: string | null;
+    fiscalYearStartMonth?: number;
+    earliestDataPeriod?: string | null;
+    autoSeedSchedules?: boolean;
+    note?: string | null;
 }
-export interface ClosingEntry {
-    entryId: string;
-    status: string;
+export interface ClosePeriodOptions {
+    note?: string | null;
+    allowStaleSync?: boolean;
+}
+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 CreateScheduleOptions {
     name: string;
@@ -85,7 +109,7 @@ export interface CreateScheduleOptions {
     entryTemplate: {
         debitElementId: string;
         creditElementId: string;
-        entryType?: string;
+        entryType?: LedgerEntryType;
         memoTemplate?: string;
     };
     taxonomyId?: string;
@@ -97,69 +121,81 @@ export interface CreateScheduleOptions {
         assetElementId?: string;
     };
 }
+interface LedgerClientConfig {
+    baseUrl: string;
+    credentials?: 'include' | 'same-origin' | 'omit';
+    headers?: Record<string, string>;
+    token?: string;
+}
 export declare class LedgerClient {
     private config;
-    constructor(config: {
-        baseUrl: string;
-        credentials?: 'include' | 'same-origin' | 'omit';
-        headers?: Record<string, string>;
-        token?: string;
-    });
-    /**
-     * Get the entity (company/organization) for this graph.
-     */
-    getEntity(graphId: string): Promise<LedgerEntity | null>;
     /**
-     * List accounts (flat).
+     * Per-graph GraphQL client cache. The first call for a given graph
+     * creates a `GraphQLClient` bound to `/extensions/{graph_id}/graphql`;
+     * subsequent calls reuse it.
      */
-    listAccounts(graphId: string): Promise<AccountListResponse>;
+    private gql;
+    constructor(config: LedgerClientConfig);
     /**
-     * Get the account tree (hierarchical).
+     * Get the entity (company/organization) for this graph.
+     * Returns null when the ledger has no entity yet.
      */
-    getAccountTree(graphId: string): Promise<AccountTreeResponse>;
+    getEntity(graphId: string): Promise<LedgerEntity | null>;
+    /** List all entities for this graph, optionally filtered by source system. */
+    listEntities(graphId: string, options?: {
+        source?: string;
+    }): Promise<LedgerEntitySummary[]>;
     /**
-     * List transactions with optional date filters.
+     * Update the entity for this graph. Only non-null fields are applied.
+     * Returns the updated entity.
      */
+    updateEntity(graphId: string, updates: UpdateEntityRequest): Promise<LedgerEntity>;
+    /** Ledger rollup counts + QB sync metadata. */
+    getSummary(graphId: string): Promise<LedgerSummary | null>;
+    /** List CoA accounts with optional filters and pagination. */
+    listAccounts(graphId: string, options?: {
+        classification?: string;
+        isActive?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<LedgerAccountList | null>;
+    /** Hierarchical Chart of Accounts (up to 4 levels deep). */
+    getAccountTree(graphId: string): Promise<LedgerAccountTree | null>;
+    /** Accounts rolled up to reporting concepts via a mapping structure. */
+    getAccountRollups(graphId: string, options?: {
+        mappingId?: string;
+        startDate?: string;
+        endDate?: string;
+    }): Promise<LedgerAccountRollups | null>;
+    /** List transactions with optional type + date filters and pagination. */
     listTransactions(graphId: string, options?: {
+        type?: string;
         startDate?: string;
         endDate?: string;
         limit?: number;
         offset?: number;
-    }): Promise<LedgerTransactionListResponse>;
-    /**
-     * Get transaction detail with entries and line items.
-     */
-    getTransaction(graphId: string, transactionId: string): Promise<LedgerTransactionDetailResponse>;
-    /**
-     * Get trial balance (CoA-level debits/credits).
-     */
+    }): Promise<LedgerTransactionList | null>;
+    /** Get transaction detail with entries + line items. */
+    getTransaction(graphId: string, transactionId: string): Promise<LedgerTransaction | null>;
+    /** Trial balance by raw CoA account. */
     getTrialBalance(graphId: string, options?: {
         startDate?: string;
         endDate?: string;
-    }): Promise<TrialBalanceResponse>;
-    /**
-     * Get mapped trial balance (CoA rolled up to GAAP concepts).
-     */
-    getMappedTrialBalance(graphId: string, options?: {
-        mappingId?: string;
+    }): Promise<LedgerTrialBalance | null>;
+    /** Trial balance rolled up to GAAP reporting concepts via a mapping. */
+    getMappedTrialBalance(graphId: string, mappingId: string, options?: {
         startDate?: string;
         endDate?: string;
-    }): Promise<unknown>;
-    /**
-     * Get ledger summary (account count, transaction count, date range).
-     */
-    getSummary(graphId: string): Promise<LedgerSummaryResponse>;
-    /**
-     * Get the reporting taxonomy (US GAAP seed).
-     */
-    getReportingTaxonomy(graphId: string): Promise<unknown>;
-    /**
-     * List reporting structures (IS, BS, CF) for a taxonomy.
-     */
-    listStructures(graphId: string, taxonomyId?: string): Promise<Structure[]>;
-    /**
-     * List elements (CoA accounts, GAAP concepts, etc.).
-     */
+    }): Promise<LedgerMappedTrialBalance | null>;
+    /** Get the locked US GAAP reporting taxonomy for this graph. */
+    getReportingTaxonomy(graphId: string): Promise<LedgerReportingTaxonomy | null>;
+    /** List active taxonomies with optional type filter. */
+    listTaxonomies(graphId: string, options?: {
+        taxonomyType?: string;
+    }): Promise<LedgerTaxonomy[]>;
+    /** Create a new taxonomy (used for CoA + mapping taxonomies). */
+    createTaxonomy(graphId: string, body: CreateTaxonomyRequest): Promise<Record<string, unknown>>;
+    /** List elements (CoA accounts, GAAP concepts, etc.) with filters. */
     listElements(graphId: string, options?: {
         taxonomyId?: string;
         source?: string;
@@ -167,76 +203,88 @@ export declare class LedgerClient {
         isAbstract?: boolean;
         limit?: number;
         offset?: number;
-    }): Promise<unknown>;
-    /**
-     * Create a new CoA→GAAP mapping structure.
-     * Returns the created mapping info.
-     */
-    createMappingStructure(graphId: string, options?: {
-        name?: string;
-        description?: string;
+    }): Promise<LedgerElementList | null>;
+    /** CoA elements not yet mapped to a reporting concept. */
+    listUnmappedElements(graphId: string, options?: {
+        mappingId?: string;
+    }): Promise<LedgerUnmappedElement[]>;
+    /** List reporting structures (IS, BS, CF, schedules) with optional filters. */
+    listStructures(graphId: string, options?: {
         taxonomyId?: string;
-    }): Promise<MappingInfo>;
-    /**
-     * List available CoA→GAAP mapping structures.
-     */
-    listMappings(graphId: string): Promise<MappingInfo[]>;
+        structureType?: string;
+    }): Promise<LedgerStructure[]>;
     /**
-     * Get mapping detail — all associations with element names.
+     * Create a new structure. Most common use is a CoA→reporting mapping
+     * structure; also used for custom statement + schedule structures.
      */
-    getMappingDetail(graphId: string, mappingId: string): Promise<MappingDetailResponse>;
-    /**
-     * Get mapping coverage — how many CoA elements are mapped.
-     */
-    getMappingCoverage(graphId: string, mappingId: string): Promise<MappingCoverage>;
-    /**
-     * Create a manual mapping association (CoA element → GAAP element).
-     */
-    createMapping(graphId: string, mappingId: string, fromElementId: string, toElementId: string, confidence?: number): Promise<void>;
-    /**
-     * Delete a mapping association.
-     */
-    deleteMapping(graphId: string, mappingId: string, associationId: string): Promise<void>;
-    /**
-     * Trigger AI auto-mapping (MappingAgent).
-     * Returns immediately — the agent runs in the background.
-     */
-    autoMap(graphId: string, mappingId: string): Promise<{
-        operationId?: string;
+    createStructure(graphId: string, body: CreateStructureRequest): Promise<LedgerMappingInfo>;
+    /** List active CoA→reporting mapping structures. */
+    listMappings(graphId: string): Promise<LedgerMappingInfo[]>;
+    /** Get a mapping structure with all its associations. */
+    getMapping(graphId: string, mappingId: string): Promise<LedgerMapping | null>;
+    /** Mapping coverage stats — how many CoA elements are mapped. */
+    getMappingCoverage(graphId: string, mappingId: string): Promise<LedgerMappingCoverage | null>;
+    /** Create a manual mapping association between two elements. */
+    createMappingAssociation(graphId: string, body: CreateMappingAssociationOperation): Promise<Record<string, unknown>>;
+    /** Delete a mapping association. */
+    deleteMappingAssociation(graphId: string, body: DeleteMappingAssociationOperation): Promise<{
+        deleted: boolean;
     }>;
     /**
-     * Create a schedule with pre-generated monthly facts.
+     * 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`.
      */
+    autoMapElements(graphId: string, body: AutoMapElementsOperation): Promise<{
+        operationId: string;
+        status: OperationEnvelope['status'];
+    }>;
+    /** List all schedule structures with metadata. */
+    listSchedules(graphId: string): Promise<LedgerSchedule[]>;
+    /** Schedule facts optionally filtered by period window. */
+    getScheduleFacts(graphId: string, structureId: string, options?: {
+        periodStart?: string;
+        periodEnd?: string;
+    }): Promise<LedgerScheduleFact[]>;
+    /** Create a new schedule with pre-generated monthly facts. */
     createSchedule(graphId: string, options: CreateScheduleOptions): Promise<ScheduleCreated>;
+    /** Truncate a schedule — end it early at `newEndDate`. */
+    truncateSchedule(graphId: string, structureId: string, options: TruncateScheduleOptions): Promise<TruncateScheduleResult>;
+    /** Close status for all schedules in a fiscal period. */
+    getPeriodCloseStatus(graphId: string, periodStart: string, periodEnd: string): Promise<LedgerPeriodCloseStatus | null>;
+    /** All draft entries in a period, fully expanded for review pre-close. */
+    listPeriodDrafts(graphId: string, period: string): Promise<LedgerPeriodDrafts | null>;
     /**
-     * List all schedules for a graph.
+     * Idempotently create (or refresh) a draft closing entry from a
+     * schedule for a period. See `ClosingEntryOutcome` for semantics.
      */
-    listSchedules(graphId: string): Promise<Schedule[]>;
-    /**
-     * Get facts for a schedule, optionally filtered by period.
-     */
-    getScheduleFacts(graphId: string, structureId: string, periodStart?: string, periodEnd?: string): Promise<ScheduleFact[]>;
-    /**
-     * Get close status for all schedules in a fiscal period.
-     */
-    getPeriodCloseStatus(graphId: string, periodStart: string, periodEnd: string): Promise<PeriodCloseStatus>;
+    createClosingEntry(graphId: string, structureId: string, postingDate: string, periodStart: string, periodEnd: string, memo?: string): Promise<ClosingEntry>;
     /**
-     * Create a draft closing entry from a schedule's facts for a period.
+     * Create a manual balanced closing entry (not tied to a schedule).
+     * Used for disposals, adjustments, and one-off closing events.
      */
-    createClosingEntry(graphId: string, structureId: string, postingDate: string, periodStart: string, periodEnd: string, memo?: string): Promise<ClosingEntry>;
+    createManualClosingEntry(graphId: string, options: CreateManualClosingEntryOptions): Promise<ClosingEntry>;
+    /** Grouped closing book structures for the close-screen sidebar. */
+    getClosingBookStructures(graphId: string): Promise<LedgerClosingBookStructures | null>;
+    /** Current fiscal calendar state — pointers, gap, closeable status. */
+    getFiscalCalendar(graphId: string): Promise<LedgerFiscalCalendar | null>;
+    /** One-time ledger initialization — seed fiscal calendar + periods. */
+    initializeLedger(graphId: string, options?: InitializeLedgerOptions): Promise<InitializeLedgerResult>;
+    /** Set the user-controlled close target (YYYY-MM). */
+    setCloseTarget(graphId: string, period: string, note?: string | null): Promise<LedgerFiscalCalendar>;
+    /** Close a fiscal period — the final commit action. */
+    closePeriod(graphId: string, period: string, options?: ClosePeriodOptions): Promise<ClosePeriodResult>;
+    /** Reopen a closed fiscal period. Requires a reason for the audit log. */
+    reopenPeriod(graphId: string, period: string, reason: string, note?: string | null): Promise<LedgerFiscalCalendar>;
     /**
-     * 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.
      */
-    getClosingBookStructures(graphId: string): Promise<ClosingBookStructuresResponse>;
+    private gqlQuery;
     /**
-     * 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.
      */
-    getAccountRollups(graphId: string, options?: {
-        mappingId?: string;
-        startDate?: string;
-        endDate?: string;
-    }): Promise<AccountRollupsResponse>;
+    private callOperation;
 }
+export {};