@robosystems/client 0.3.9 → 0.3.11

package/artifacts/LedgerClient.js

@@ -76,36 +76,6 @@ class LedgerClient {
     async getTransaction(graphId, transactionId) {
         return this.gqlQuery(graphId, graphql_1.GetLedgerTransactionDocument, { transactionId }, 'Get transaction', (data) => data.transaction);
     }
-    /**
-     * 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.
-     */
-    async createTransaction(graphId, options) {
-        const body = {
-            type: options.type,
-            date: options.date,
-            amount: options.amount,
-            currency: options.currency ?? 'USD',
-            status: options.status ?? 'pending',
-            description: options.description ?? null,
-            merchant_name: options.merchantName ?? null,
-            reference_number: options.referenceNumber ?? null,
-            number: options.number ?? null,
-            category: options.category ?? null,
-            due_date: options.dueDate ?? null,
-        };
-        const headers = options.idempotencyKey
-            ? { 'Idempotency-Key': options.idempotencyKey }
-            : undefined;
-        const envelope = await this.callOperation('Create transaction', (0, sdk_gen_1.opCreateTransaction)({ path: { graph_id: graphId }, body, headers }));
-        return (envelope.result ?? {});
-    }
     // ── Trial Balance ──────────────────────────────────────────────────
     /** Trial balance by raw CoA account. */
     async getTrialBalance(graphId, options) {
@@ -132,22 +102,6 @@ class LedgerClient {
         const list = await this.gqlQuery(graphId, graphql_1.ListLedgerTaxonomiesDocument, { taxonomyType: options?.taxonomyType ?? null }, 'List taxonomies', (data) => data.taxonomies);
         return list?.taxonomies ?? [];
     }
-    /** 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 ?? {});
-    }
-    /** Update mutable fields on a taxonomy. `taxonomy_type` is immutable. */
-    async updateTaxonomy(graphId, body) {
-        const envelope = await this.callOperation('Update taxonomy', (0, sdk_gen_1.opUpdateTaxonomy)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
-    /** Soft-delete a taxonomy (`is_active=false`). */
-    async deleteTaxonomy(graphId, taxonomyId) {
-        const body = { taxonomy_id: taxonomyId };
-        const envelope = await this.callOperation('Delete taxonomy', (0, sdk_gen_1.opDeleteTaxonomy)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
     /**
      * Link the graph's entity to a taxonomy (ENTITY_HAS_TAXONOMY edge).
      * Idempotent — returns existing linkage if already present.
@@ -156,6 +110,25 @@ class LedgerClient {
         const envelope = await this.callOperation('Link entity taxonomy', (0, sdk_gen_1.opLinkEntityTaxonomy)({ path: { graph_id: graphId }, body }));
         return (envelope.result ?? {});
     }
+    /**
+     * Create a taxonomy block atomically (taxonomy + structures + elements +
+     * associations + rules in one envelope).
+     */
+    async createTaxonomyBlock(graphId, body, idempotencyKey) {
+        const headers = idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined;
+        const envelope = await this.callOperation('Create taxonomy block', (0, sdk_gen_1.opCreateTaxonomyBlock)({ path: { graph_id: graphId }, body, headers }));
+        return (envelope.result ?? {});
+    }
+    /** Update a taxonomy block — add/update/remove elements, structures, associations, or rules. */
+    async updateTaxonomyBlock(graphId, body) {
+        const envelope = await this.callOperation('Update taxonomy block', (0, sdk_gen_1.opUpdateTaxonomyBlock)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    /** Delete a taxonomy block. Cascades through elements, structures, and associations. */
+    async deleteTaxonomyBlock(graphId, body) {
+        const envelope = await this.callOperation('Delete taxonomy block', (0, sdk_gen_1.opDeleteTaxonomyBlock)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? { deleted: true });
+    }
     /** List elements (CoA accounts, GAAP concepts, etc.) with filters. */
     async listElements(graphId, options) {
         return this.gqlQuery(graphId, graphql_1.ListLedgerElementsDocument, {
@@ -171,22 +144,6 @@ class LedgerClient {
     async listUnmappedElements(graphId, options) {
         return this.gqlQuery(graphId, graphql_1.ListLedgerUnmappedElementsDocument, { mappingId: options?.mappingId ?? null }, 'List unmapped elements', (data) => data.unmappedElements);
     }
-    /** Create a new element within a taxonomy (native CoA account, etc.). */
-    async createElement(graphId, body) {
-        const envelope = await this.callOperation('Create element', (0, sdk_gen_1.opCreateElement)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
-    /** Update mutable fields on an element. `taxonomy_id` and `source` are immutable. */
-    async updateElement(graphId, body) {
-        const envelope = await this.callOperation('Update element', (0, sdk_gen_1.opUpdateElement)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
-    /** Soft-delete an element (`is_active=false`). */
-    async deleteElement(graphId, elementId) {
-        const body = { element_id: elementId };
-        const envelope = await this.callOperation('Delete element', (0, sdk_gen_1.opDeleteElement)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
     // ── Structures ──────────────────────────────────────────────────────
     /** List reporting structures (IS, BS, CF, schedules) with optional filters. */
     async listStructures(graphId, options) {
@@ -196,36 +153,6 @@ class LedgerClient {
         }, 'List structures', (data) => data.structures);
         return list?.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;
-    }
-    /** Convenience wrapper — create a CoA→GAAP mapping structure. */
-    async createMappingStructure(graphId, options) {
-        const body = {
-            name: options?.name ?? 'CoA to Reporting',
-            structure_type: 'coa_mapping',
-            taxonomy_id: options?.taxonomyId ?? 'tax_usgaap_reporting',
-            description: options?.description ?? 'Map Chart of Accounts to US GAAP reporting concepts',
-        };
-        const envelope = await this.callOperation('Create mapping structure', (0, sdk_gen_1.opCreateStructure)({ path: { graph_id: graphId }, body }));
-        return envelope.result;
-    }
-    /** Update mutable fields on a structure. `structure_type` is immutable. */
-    async updateStructure(graphId, body) {
-        const envelope = await this.callOperation('Update structure', (0, sdk_gen_1.opUpdateStructure)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
-    /** Soft-delete a structure (`is_active=false`). */
-    async deleteStructure(graphId, structureId) {
-        const body = { structure_id: structureId };
-        const envelope = await this.callOperation('Delete structure', (0, sdk_gen_1.opDeleteStructure)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
     // ── Mappings ────────────────────────────────────────────────────────
     /** List active CoA→reporting mapping structures. */
     async listMappings(graphId) {
@@ -259,23 +186,6 @@ class LedgerClient {
         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 };
     }
-    /** Bulk create associations within a single structure, atomically. */
-    async createAssociations(graphId, structureId, associations) {
-        const body = { structure_id: structureId, associations };
-        const envelope = await this.callOperation('Create associations', (0, sdk_gen_1.opCreateAssociations)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
-    /** Update mutable fields on an association (order, weight, confidence). */
-    async updateAssociation(graphId, body) {
-        const envelope = await this.callOperation('Update association', (0, sdk_gen_1.opUpdateAssociation)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? {});
-    }
-    /** Hard-delete an association (any type: presentation, calculation, mapping). */
-    async deleteAssociation(graphId, associationId) {
-        const body = { association_id: associationId };
-        const envelope = await this.callOperation('Delete association', (0, sdk_gen_1.opDeleteAssociation)({ path: { graph_id: graphId }, body }));
-        return (envelope.result ?? { deleted: true });
-    }
     // ── Information Blocks ─────────────────────────────────────────────
     /**
      * Fetch an Information Block envelope by id — the generic
@@ -357,21 +267,36 @@ class LedgerClient {
         const envelope = await this.callOperation('Delete schedule', (0, sdk_gen_1.opDeleteInformationBlock)({ path: { graph_id: graphId }, body }));
         return (envelope.result ?? { deleted: true });
     }
-    /** Truncate a schedule — end it early at `newEndDate`. */
-    async truncateSchedule(graphId, structureId, options) {
+    /**
+     * 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.
+     */
+    async disposeSchedule(graphId, 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 {
-            structureId: raw.structure_id,
-            newEndDate: raw.new_end_date,
-            factsDeleted: raw.facts_deleted,
-            reason: raw.reason,
+            event_type: 'asset_disposed',
+            event_category: 'adjustment',
+            source: 'native',
+            occurred_at: options.occurredAt,
+            apply_handlers: true,
+            metadata: {
+                schedule_id: options.scheduleId,
+                proceeds: options.proceeds ?? 0,
+                proceeds_element_id: options.proceedsElementId ?? null,
+                gain_loss_element_id: options.gainLossElementId ?? null,
+                memo: options.memo ?? null,
+                reason: options.reason ?? 'asset_disposed_event',
+            },
         };
+        const envelope = await this.callOperation('Dispose schedule', (0, sdk_gen_1.opCreateEventBlock)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    /** Evaluate taxonomy rules against facts in a structure. */
+    async evaluateRules(graphId, body) {
+        const envelope = await this.callOperation('Evaluate rules', (0, sdk_gen_1.opEvaluateRules)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
     }
     // ── Period close ────────────────────────────────────────────────────
     /** Close status for all schedules in a fiscal period. */
@@ -384,37 +309,30 @@ class LedgerClient {
     }
     /**
      * Idempotently create (or refresh) a draft closing entry from a
-     * schedule for a period. See `ClosingEntryOutcome` for semantics.
+     * 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.
      */
     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 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,
-            })),
+            event_type: 'schedule_entry_due',
+            event_category: 'recognition',
+            source: 'scheduled',
+            occurred_at: `${postingDate}T00:00:00Z`,
+            apply_handlers: true,
+            metadata: {
+                schedule_id: structureId,
+                posting_date: postingDate,
+                period_start: periodStart,
+                period_end: periodEnd,
+                memo: memo ?? null,
+            },
         };
-        const envelope = await this.callOperation('Create manual closing entry', (0, sdk_gen_1.opCreateManualClosingEntry)({ path: { graph_id: graphId }, body }));
-        return rawToClosingEntry(envelope.result);
+        const envelope = await this.callOperation('Create closing entry', (0, sdk_gen_1.opCreateEventBlock)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
     }
     // ── Closing book ───────────────────────────────────────────────────
     /** Grouped closing book structures for the close-screen sidebar. */
@@ -479,28 +397,43 @@ 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.
      */
     async createJournalEntry(graphId, options) {
         const body = {
-            posting_date: options.postingDate,
-            memo: options.memo,
-            line_items: options.lineItems.map((li) => ({
-                element_id: li.elementId,
-                debit_amount: li.debitAmount,
-                credit_amount: li.creditAmount,
-                description: li.description ?? null,
-            })),
-            type: options.type,
-            status: options.status,
-            transaction_id: options.transactionId ?? null,
+            event_type: 'journal_entry_recorded',
+            event_category: 'adjustment',
+            source: 'native',
+            occurred_at: `${options.postingDate}T00:00:00Z`,
+            apply_handlers: true,
+            metadata: {
+                posting_date: options.postingDate,
+                memo: options.memo,
+                line_items: options.lineItems.map((li) => ({
+                    element_id: li.elementId,
+                    debit_amount: li.debitAmount,
+                    credit_amount: li.creditAmount,
+                    description: li.description ?? null,
+                })),
+                type: options.type ?? 'standard',
+                status: options.status ?? 'draft',
+                transaction_id: options.transactionId ?? null,
+            },
         };
-        const envelope = await this.callOperation('Create journal entry', (0, sdk_gen_1.opCreateJournalEntry)({ path: { graph_id: graphId }, body }));
+        const headers = options.idempotencyKey
+            ? { 'Idempotency-Key': options.idempotencyKey }
+            : undefined;
+        const envelope = await this.callOperation('Create journal entry', (0, sdk_gen_1.opCreateEventBlock)({ path: { graph_id: graphId }, body, headers }));
         return (envelope.result ?? {});
     }
     /** Update a draft journal entry. Posted entries are immutable. */
@@ -517,14 +450,109 @@ 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'`.
      */
     async reverseJournalEntry(graphId, entryId, options) {
+        const occurredDate = options?.postingDate ?? new Date().toISOString().slice(0, 10);
         const body = {
-            entry_id: entryId,
-            posting_date: options?.postingDate ?? null,
-            memo: options?.memo ?? null,
+            event_type: 'journal_entry_reversed',
+            event_category: 'adjustment',
+            source: 'native',
+            occurred_at: `${occurredDate}T00:00:00Z`,
+            apply_handlers: true,
+            metadata: {
+                entry_id: entryId,
+                posting_date: options?.postingDate ?? null,
+                memo: options?.memo ?? null,
+                reason: options?.reason ?? null,
+            },
         };
-        const envelope = await this.callOperation('Reverse journal entry', (0, sdk_gen_1.opReverseJournalEntry)({ path: { graph_id: graphId }, body }));
+        const envelope = await this.callOperation('Reverse journal entry', (0, sdk_gen_1.opCreateEventBlock)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    // ── Event blocks (generic preview + status transitions) ──────────────
+    /**
+     * 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.
+     */
+    async previewEventBlock(graphId, body) {
+        const envelope = await this.callOperation('Preview event block', (0, sdk_gen_1.opPreviewEventBlock)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    /**
+     * 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`.
+     */
+    async updateEventBlock(graphId, body) {
+        const envelope = await this.callOperation('Update event block', (0, sdk_gen_1.opUpdateEventBlock)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    // ── Agents (REA counterparties) ───────────────────────────────────────
+    /**
+     * 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.
+     */
+    async createAgent(graphId, body, idempotencyKey) {
+        const headers = idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined;
+        const envelope = await this.callOperation('Create agent', (0, sdk_gen_1.opCreateAgent)({ path: { graph_id: graphId }, body, headers }));
+        return (envelope.result ?? {});
+    }
+    /**
+     * Update an agent. `metadata_patch` is a partial merge into the existing
+     * metadata object; all other fields replace.
+     */
+    async updateAgent(graphId, body) {
+        const envelope = await this.callOperation('Update agent', (0, sdk_gen_1.opUpdateAgent)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    // ── Event handlers (DSL handler registry) ────────────────────────────
+    /**
+     * 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.
+     */
+    async createEventHandler(graphId, body) {
+        const envelope = await this.callOperation('Create event handler', (0, sdk_gen_1.opCreateEventHandler)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    /**
+     * Update a registered event handler. Pass `approve: true` to flip an
+     * AI-suggested handler from unapproved to active.
+     */
+    async updateEventHandler(graphId, body) {
+        const envelope = await this.callOperation('Update event handler', (0, sdk_gen_1.opUpdateEventHandler)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    // ── Financial statements (graph-backed) ──────────────────────────────
+    /**
+     * 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.
+     */
+    async liveFinancialStatement(graphId, body) {
+        const envelope = await this.callOperation('Live financial statement', (0, sdk_gen_1.opLiveFinancialStatement)({ path: { graph_id: graphId }, body }));
+        return (envelope.result ?? {});
+    }
+    /**
+     * 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`.
+     */
+    async financialStatementAnalysis(graphId, body) {
+        const envelope = await this.callOperation('Financial statement analysis', (0, sdk_gen_1.opFinancialStatementAnalysis)({ path: { graph_id: graphId }, body }));
         return (envelope.result ?? {});
     }
     // ── Fact grid (graph-backed analytical query) ─────────────────────
@@ -730,19 +758,6 @@ class LedgerClient {
 }
 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,