@robosystems/client 0.3.9 → 0.3.11

package/artifacts/LedgerClient.d.ts

@@ -1,4 +1,4 @@
-import type { AutoMapElementsOperation, BulkAssociationItem, CreateElementRequest, CreateMappingAssociationOperation, CreateStructureRequest, CreateTaxonomyRequest, CreateViewRequest, DeleteMappingAssociationOperation, LinkEntityTaxonomyRequest, OperationEnvelope, UpdateAssociationRequest, UpdateElementRequest, UpdateEntityRequest, UpdateJournalEntryRequest, UpdateStructureRequest, UpdateTaxonomyRequest } from '../types.gen';
+import type { AutoMapElementsOperation, CreateAgentRequest, CreateEventBlockRequest, CreateEventHandlerRequest, CreateMappingAssociationOperation, CreateTaxonomyBlockRequest, CreateViewRequest, DeleteMappingAssociationOperation, DeleteTaxonomyBlockRequest, EvaluateRulesRequest, FinancialStatementAnalysisRequest, LinkEntityTaxonomyRequest, LiveFinancialStatementRequest, OperationEnvelope, UpdateAgentRequest, UpdateEntityRequest, UpdateEventBlockRequest, UpdateEventHandlerRequest, UpdateJournalEntryRequest, UpdateTaxonomyBlockRequest } from '../types.gen';
 import type { TokenProvider } from './graphql/client';
 import { type GetInformationBlockQuery, type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, type GetLedgerFiscalCalendarQuery, type GetLedgerMappedTrialBalanceQuery, type GetLedgerMappingCoverageQuery, type GetLedgerMappingQuery, type GetLedgerPeriodCloseStatusQuery, type GetLedgerPeriodDraftsQuery, type GetLedgerPublishListQuery, type GetLedgerReportingTaxonomyQuery, type GetLedgerReportQuery, type GetLedgerStatementQuery, type GetLedgerSummaryQuery, type GetLedgerTransactionQuery, type GetLedgerTrialBalanceQuery, type ListInformationBlocksQuery, type ListLedgerAccountsQuery, type ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerMappingsQuery, type ListLedgerPublishListsQuery, type ListLedgerReportsQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery } from './graphql/generated/graphql';
 export type LedgerEntity = NonNullable<GetLedgerEntityQuery['entity']>;
@@ -77,18 +77,6 @@ export interface ClosePeriodResult {
     targetAutoAdvanced: boolean;
     fiscalCalendar: LedgerFiscalCalendar;
 }
-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;
     name: string;
@@ -96,12 +84,6 @@ export interface ScheduleCreated {
     totalPeriods: number;
     totalFacts: number;
 }
-export interface TruncateScheduleResult {
-    structureId: string;
-    newEndDate: string;
-    factsDeleted: number;
-    reason: string;
-}
 export type LedgerEntryType = 'standard' | 'adjusting' | 'closing' | 'reversing';
 export interface InitializeLedgerOptions {
     closedThrough?: string | null;
@@ -114,22 +96,6 @@ 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;
-    lineItems: ManualClosingLineItem[];
-    entryType?: LedgerEntryType;
-}
-export interface TruncateScheduleOptions {
-    newEndDate: string;
-    reason: string;
-}
 export interface CreateScheduleOptions {
     name: string;
     elementIds: string[];
@@ -228,30 +194,6 @@ export declare class LedgerClient {
     }): Promise<LedgerTransactionList | null>;
     /** Get transaction detail with entries + line items. */
     getTransaction(graphId: string, transactionId: string): Promise<LedgerTransaction | null>;
-    /**
-     * Create a standalone business-event Transaction without entries.
-     *
-     * Returns a `transaction_id` that can be passed to `createJournalEntry`
-     * to attach entries to this event. Use when a single event (invoice,
-     * payment, deposit) produces multiple entries over its lifecycle.
-     *
-     * `amount` is in minor currency units (cents).
-     * `type` is free-form: invoice, payment, bill, expense, deposit, etc.
-     */
-    createTransaction(graphId: string, options: {
-        type: string;
-        date: string;
-        amount: number;
-        currency?: string;
-        description?: string;
-        merchantName?: string;
-        referenceNumber?: string;
-        number?: string;
-        category?: string;
-        dueDate?: string;
-        status?: 'pending' | 'posted';
-        idempotencyKey?: string;
-    }): Promise<Record<string, unknown>>;
     /** Trial balance by raw CoA account. */
     getTrialBalance(graphId: string, options?: {
         startDate?: string;
@@ -268,17 +210,22 @@ export declare class LedgerClient {
     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>>;
-    /** Update mutable fields on a taxonomy. `taxonomy_type` is immutable. */
-    updateTaxonomy(graphId: string, body: UpdateTaxonomyRequest): Promise<Record<string, unknown>>;
-    /** Soft-delete a taxonomy (`is_active=false`). */
-    deleteTaxonomy(graphId: string, taxonomyId: string): Promise<Record<string, unknown>>;
     /**
      * Link the graph's entity to a taxonomy (ENTITY_HAS_TAXONOMY edge).
      * Idempotent — returns existing linkage if already present.
      */
     linkEntityTaxonomy(graphId: string, body: LinkEntityTaxonomyRequest): Promise<Record<string, unknown>>;
+    /**
+     * Create a taxonomy block atomically (taxonomy + structures + elements +
+     * associations + rules in one envelope).
+     */
+    createTaxonomyBlock(graphId: string, body: CreateTaxonomyBlockRequest, idempotencyKey?: string): Promise<Record<string, unknown>>;
+    /** Update a taxonomy block — add/update/remove elements, structures, associations, or rules. */
+    updateTaxonomyBlock(graphId: string, body: UpdateTaxonomyBlockRequest): Promise<Record<string, unknown>>;
+    /** Delete a taxonomy block. Cascades through elements, structures, and associations. */
+    deleteTaxonomyBlock(graphId: string, body: DeleteTaxonomyBlockRequest): Promise<{
+        deleted: boolean;
+    }>;
     /** List elements (CoA accounts, GAAP concepts, etc.) with filters. */
     listElements(graphId: string, options?: {
         taxonomyId?: string;
@@ -292,32 +239,11 @@ export declare class LedgerClient {
     listUnmappedElements(graphId: string, options?: {
         mappingId?: string;
     }): Promise<LedgerUnmappedElement[]>;
-    /** Create a new element within a taxonomy (native CoA account, etc.). */
-    createElement(graphId: string, body: CreateElementRequest): Promise<Record<string, unknown>>;
-    /** Update mutable fields on an element. `taxonomy_id` and `source` are immutable. */
-    updateElement(graphId: string, body: UpdateElementRequest): Promise<Record<string, unknown>>;
-    /** Soft-delete an element (`is_active=false`). */
-    deleteElement(graphId: string, elementId: string): Promise<Record<string, unknown>>;
     /** List reporting structures (IS, BS, CF, schedules) with optional filters. */
     listStructures(graphId: string, options?: {
         taxonomyId?: string;
         structureType?: string;
     }): Promise<LedgerStructure[]>;
-    /**
-     * Create a new structure. Most common use is a CoA→reporting mapping
-     * structure; also used for custom statement + schedule structures.
-     */
-    createStructure(graphId: string, body: CreateStructureRequest): Promise<LedgerMappingInfo>;
-    /** Convenience wrapper — create a CoA→GAAP mapping structure. */
-    createMappingStructure(graphId: string, options?: {
-        name?: string;
-        description?: string | null;
-        taxonomyId?: string;
-    }): Promise<LedgerMappingInfo>;
-    /** Update mutable fields on a structure. `structure_type` is immutable. */
-    updateStructure(graphId: string, body: UpdateStructureRequest): Promise<Record<string, unknown>>;
-    /** Soft-delete a structure (`is_active=false`). */
-    deleteStructure(graphId: string, structureId: string): Promise<Record<string, unknown>>;
     /** List active CoA→reporting mapping structures. */
     listMappings(graphId: string): Promise<LedgerMappingInfo[]>;
     /** Get a mapping structure with all its associations. */
@@ -339,14 +265,6 @@ export declare class LedgerClient {
         operationId: string;
         status: OperationEnvelope['status'];
     }>;
-    /** Bulk create associations within a single structure, atomically. */
-    createAssociations(graphId: string, structureId: string, associations: BulkAssociationItem[]): Promise<Record<string, unknown>>;
-    /** Update mutable fields on an association (order, weight, confidence). */
-    updateAssociation(graphId: string, body: UpdateAssociationRequest): Promise<Record<string, unknown>>;
-    /** Hard-delete an association (any type: presentation, calculation, mapping). */
-    deleteAssociation(graphId: string, associationId: string): Promise<{
-        deleted: boolean;
-    }>;
     /**
      * Fetch an Information Block envelope by id — the generic
      * cross-block-type read. Returns `null` when the block doesn't exist
@@ -374,22 +292,38 @@ export declare class LedgerClient {
     deleteSchedule(graphId: string, structureId: string): Promise<{
         deleted: boolean;
     }>;
-    /** Truncate a schedule — end it early at `newEndDate`. */
-    truncateSchedule(graphId: string, structureId: string, options: TruncateScheduleOptions): Promise<TruncateScheduleResult>;
+    /**
+     * Dispose of a schedule asset — atomically truncates forward facts,
+     * deletes the SumEquals rule, and posts a balanced disposal entry.
+     *
+     * Routes through `create-event-block` with `event_type='asset_disposed'`.
+     * `occurred_at` is required and represents the disposal date.
+     */
+    disposeSchedule(graphId: string, options: {
+        scheduleId: string;
+        occurredAt: string;
+        proceeds?: number;
+        proceedsElementId?: string | null;
+        gainLossElementId?: string | null;
+        memo?: string | null;
+        reason?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Evaluate taxonomy rules against facts in a structure. */
+    evaluateRules(graphId: string, body: EvaluateRulesRequest): Promise<Record<string, unknown>>;
     /** 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>;
     /**
      * Idempotently create (or refresh) a draft closing entry from a
-     * schedule for a period. See `ClosingEntryOutcome` for semantics.
-     */
-    createClosingEntry(graphId: string, structureId: string, postingDate: string, periodStart: string, periodEnd: string, memo?: string): Promise<ClosingEntry>;
-    /**
-     * Create a manual balanced closing entry (not tied to a schedule).
-     * Used for disposals, adjustments, and one-off closing events.
+     * schedule for a period.
+     *
+     * Routes through `create-event-block` with
+     * `event_type='schedule_entry_due'`. Returns the EventBlockEnvelope —
+     * the underlying handler is idempotent and dispatches to one of
+     * created / unchanged / regenerated / removed / skipped internally.
      */
-    createManualClosingEntry(graphId: string, options: CreateManualClosingEntryOptions): Promise<ClosingEntry>;
+    createClosingEntry(graphId: string, structureId: string, postingDate: string, periodStart: string, periodEnd: string, memo?: string): Promise<Record<string, unknown>>;
     /** Grouped closing book structures for the close-screen sidebar. */
     getClosingBookStructures(graphId: string): Promise<LedgerClosingBookStructures | null>;
     /** Current fiscal calendar state — pointers, gap, closeable status. */
@@ -405,12 +339,17 @@ export declare class LedgerClient {
     /**
      * Create a journal entry with balanced line items (DR=CR enforced).
      *
-     * Defaults to `status='draft'`. Pass `status='posted'` for historical
-     * data import where entries represent already-happened business events.
+     * Routes through `create-event-block` with
+     * `event_type='journal_entry_recorded'` — the Python handler forwards
+     * to the internal journal-entry command. Defaults to `status='draft'`;
+     * pass `status='posted'` for historical data imports.
      *
      * Supply `idempotencyKey` to make the call safe to retry — replays
      * within 24 hours return the same envelope. Reusing the key with a
      * different body returns HTTP 409.
+     *
+     * Returns the EventBlockEnvelope (event row fields); query the ledger
+     * separately if you need the resulting entry_id.
      */
     createJournalEntry(graphId: string, options: CreateJournalEntryOptions): Promise<Record<string, unknown>>;
     /** Update a draft journal entry. Posted entries are immutable. */
@@ -422,11 +361,69 @@ export declare class LedgerClient {
     /**
      * Reverse a posted journal entry — creates an offsetting entry and marks
      * the original as reversed.
+     *
+     * Routes through `create-event-block` with
+     * `event_type='journal_entry_reversed'`.
      */
     reverseJournalEntry(graphId: string, entryId: string, options?: {
         postingDate?: string | null;
         memo?: string | null;
+        reason?: string | null;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Dry-run an event block — resolve the handler, evaluate metadata, and
+     * return the planned GL rows without writing anything. Companion to
+     * `createJournalEntry` / `reverseJournalEntry` / `createClosingEntry` /
+     * `disposeSchedule`: pass the same body you'd send to those methods
+     * (the underlying `CreateEventBlockRequest`) and inspect what the
+     * handler would do.
+     */
+    previewEventBlock(graphId: string, body: CreateEventBlockRequest): Promise<Record<string, unknown>>;
+    /**
+     * Apply a status transition and/or field corrections to an existing
+     * event block. Use for posting drafts (`classified` → `committed` →
+     * `fulfilled`), voiding, superseding (correction chains), or patching
+     * `description` / `effective_at` / `metadata`.
+     */
+    updateEventBlock(graphId: string, body: UpdateEventBlockRequest): Promise<Record<string, unknown>>;
+    /**
+     * Create an agent — REA counterparty (customer, vendor, employee, etc.)
+     * referenced by event blocks via `agent_id`. `(source, external_id)` is
+     * unique when `external_id` is provided, so external-source ingestion is
+     * idempotent at the DB level.
+     */
+    createAgent(graphId: string, body: CreateAgentRequest, idempotencyKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Update an agent. `metadata_patch` is a partial merge into the existing
+     * metadata object; all other fields replace.
+     */
+    updateAgent(graphId: string, body: UpdateAgentRequest): Promise<Record<string, unknown>>;
+    /**
+     * Register a tenant-configurable event handler — DSL row in the
+     * `event_handlers` table that drives `create-event-block` for event
+     * types not covered by a Python handler. Match selectors plus a
+     * `transaction_template` describing the GL rows to produce.
+     */
+    createEventHandler(graphId: string, body: CreateEventHandlerRequest): Promise<Record<string, unknown>>;
+    /**
+     * Update a registered event handler. Pass `approve: true` to flip an
+     * AI-suggested handler from unapproved to active.
+     */
+    updateEventHandler(graphId: string, body: UpdateEventHandlerRequest): Promise<Record<string, unknown>>;
+    /**
+     * Live financial statement — pulls facts directly from the graph for
+     * an explicit period window (or fiscal year) and returns the statement
+     * shape without a persisted Report row. Useful for ad-hoc previews and
+     * dashboards.
+     */
+    liveFinancialStatement(graphId: string, body: LiveFinancialStatementRequest): Promise<Record<string, unknown>>;
+    /**
+     * Run a financial statement analysis against an existing report.
+     * On shared-repo graphs (e.g. SEC), `ticker` is required; on tenant
+     * graphs it's ignored. Either pass an explicit `report_id` or let the
+     * server auto-resolve via `fiscal_year` + `period_type`.
+     */
+    financialStatementAnalysis(graphId: string, body: FinancialStatementAnalysisRequest): Promise<Record<string, unknown>>;
     /**
      * Build a multi-dimensional fact grid against the graph schema.
      *