@robosystems/client 0.3.8 → 0.3.10

package/artifacts/LedgerClient.ts

@@ -29,27 +29,23 @@ import {
   opAutoMapElements,
   opBuildFactGrid,
   opClosePeriod,
-  opCreateAssociations,
   opCreateClosingEntry,
-  opCreateElement,
+  opCreateInformationBlock,
   opCreateJournalEntry,
   opCreateManualClosingEntry,
   opCreateMappingAssociation,
   opCreatePublishList,
   opCreateReport,
-  opCreateSchedule,
-  opCreateStructure,
-  opCreateTaxonomy,
+  opCreateTaxonomyBlock,
   opCreateTransaction,
-  opDeleteAssociation,
-  opDeleteElement,
+  opDeleteInformationBlock,
   opDeleteJournalEntry,
   opDeleteMappingAssociation,
   opDeletePublishList,
   opDeleteReport,
-  opDeleteSchedule,
-  opDeleteStructure,
-  opDeleteTaxonomy,
+  opDeleteTaxonomyBlock,
+  opDisposeSchedule,
+  opEvaluateRules,
   opInitializeLedger,
   opLinkEntityTaxonomy,
   opRegenerateReport,
@@ -59,40 +55,32 @@ import {
   opSetCloseTarget,
   opShareReport,
   opTruncateSchedule,
-  opUpdateAssociation,
-  opUpdateElement,
   opUpdateEntity,
+  opUpdateInformationBlock,
   opUpdateJournalEntry,
   opUpdatePublishList,
-  opUpdateSchedule,
-  opUpdateStructure,
-  opUpdateTaxonomy,
+  opUpdateTaxonomyBlock,
 } from '../sdk.gen'
 import type {
   AddPublishListMembersOperation,
   AutoMapElementsOperation,
-  BulkAssociationItem,
-  BulkCreateAssociationsRequest,
   ClosePeriodOperation,
   CreateClosingEntryOperation,
-  CreateElementRequest,
+  CreateInformationBlockRequest,
   CreateJournalEntryRequest,
   CreateManualClosingEntryRequest,
   CreateMappingAssociationOperation,
   CreatePublishListRequest,
   CreateReportRequest,
-  CreateScheduleRequest,
-  CreateStructureRequest,
-  CreateTaxonomyRequest,
+  CreateTaxonomyBlockRequest,
   CreateTransactionRequest,
   CreateViewRequest,
-  DeleteAssociationRequest,
-  DeleteElementRequest,
+  DeleteInformationBlockRequest,
   DeleteJournalEntryRequest,
   DeleteMappingAssociationOperation,
-  DeleteScheduleRequest,
-  DeleteStructureRequest,
-  DeleteTaxonomyRequest,
+  DeleteTaxonomyBlockRequest,
+  DisposeScheduleRequest,
+  EvaluateRulesRequest,
   InitializeLedgerRequest,
   JournalEntryLineItemInput,
   LinkEntityTaxonomyRequest,
@@ -101,18 +89,16 @@ import type {
   ReverseJournalEntryRequest,
   SetCloseTargetOperation,
   TruncateScheduleOperation,
-  UpdateAssociationRequest,
-  UpdateElementRequest,
   UpdateEntityRequest,
+  UpdateInformationBlockRequest,
   UpdateJournalEntryRequest,
   UpdatePublishListOperation,
-  UpdateScheduleRequest,
-  UpdateStructureRequest,
-  UpdateTaxonomyRequest,
+  UpdateTaxonomyBlockRequest,
 } from '../types.gen'
 import type { TokenProvider } from './graphql/client'
 import { GraphQLClientCache } from './graphql/client'
 import {
+  GetInformationBlockDocument,
   GetLedgerAccountRollupsDocument,
   GetLedgerAccountTreeDocument,
   GetLedgerClosingBookStructuresDocument,
@@ -126,22 +112,22 @@ import {
   GetLedgerPublishListDocument,
   GetLedgerReportDocument,
   GetLedgerReportingTaxonomyDocument,
-  GetLedgerScheduleFactsDocument,
   GetLedgerStatementDocument,
   GetLedgerSummaryDocument,
   GetLedgerTransactionDocument,
   GetLedgerTrialBalanceDocument,
+  ListInformationBlocksDocument,
   ListLedgerAccountsDocument,
   ListLedgerElementsDocument,
   ListLedgerEntitiesDocument,
   ListLedgerMappingsDocument,
   ListLedgerPublishListsDocument,
   ListLedgerReportsDocument,
-  ListLedgerSchedulesDocument,
   ListLedgerStructuresDocument,
   ListLedgerTaxonomiesDocument,
   ListLedgerTransactionsDocument,
   ListLedgerUnmappedElementsDocument,
+  type GetInformationBlockQuery,
   type GetLedgerAccountRollupsQuery,
   type GetLedgerAccountTreeQuery,
   type GetLedgerClosingBookStructuresQuery,
@@ -155,18 +141,17 @@ import {
   type GetLedgerPublishListQuery,
   type GetLedgerReportingTaxonomyQuery,
   type GetLedgerReportQuery,
-  type GetLedgerScheduleFactsQuery,
   type GetLedgerStatementQuery,
   type GetLedgerSummaryQuery,
   type GetLedgerTransactionQuery,
   type GetLedgerTrialBalanceQuery,
+  type ListInformationBlocksQuery,
   type ListLedgerAccountsQuery,
   type ListLedgerElementsQuery,
   type ListLedgerEntitiesQuery,
   type ListLedgerMappingsQuery,
   type ListLedgerPublishListsQuery,
   type ListLedgerReportsQuery,
-  type ListLedgerSchedulesQuery,
   type ListLedgerStructuresQuery,
   type ListLedgerTaxonomiesQuery,
   type ListLedgerTransactionsQuery,
@@ -217,10 +202,11 @@ 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 InformationBlock = NonNullable<GetInformationBlockQuery['informationBlock']>
+export type InformationBlockList = ListInformationBlocksQuery['informationBlocks']
+export type InformationBlockElement = InformationBlock['elements'][number]
+export type InformationBlockConnection = InformationBlock['connections'][number]
+export type InformationBlockFact = InformationBlock['facts'][number]
 
 export type LedgerPeriodCloseStatus = NonNullable<
   GetLedgerPeriodCloseStatusQuery['periodCloseStatus']
@@ -756,53 +742,60 @@ export class LedgerClient {
     return list?.taxonomies ?? []
   }
 
-  /** Create a new taxonomy (used for CoA + mapping taxonomies). */
-  async createTaxonomy(
+  /**
+   * Link the graph's entity to a taxonomy (ENTITY_HAS_TAXONOMY edge).
+   * Idempotent — returns existing linkage if already present.
+   */
+  async linkEntityTaxonomy(
     graphId: string,
-    body: CreateTaxonomyRequest
+    body: LinkEntityTaxonomyRequest
   ): Promise<Record<string, unknown>> {
     const envelope = await this.callOperation(
-      'Create taxonomy',
-      opCreateTaxonomy({ path: { graph_id: graphId }, body })
+      'Link entity taxonomy',
+      opLinkEntityTaxonomy({ path: { graph_id: graphId }, body })
     )
     return (envelope.result ?? {}) as Record<string, unknown>
   }
 
-  /** Update mutable fields on a taxonomy. `taxonomy_type` is immutable. */
-  async updateTaxonomy(
+  /**
+   * Create a taxonomy block atomically (taxonomy + structures + elements +
+   * associations + rules in one envelope).
+   */
+  async createTaxonomyBlock(
     graphId: string,
-    body: UpdateTaxonomyRequest
+    body: CreateTaxonomyBlockRequest,
+    idempotencyKey?: string
   ): Promise<Record<string, unknown>> {
+    const headers = idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined
     const envelope = await this.callOperation(
-      'Update taxonomy',
-      opUpdateTaxonomy({ path: { graph_id: graphId }, body })
+      'Create taxonomy block',
+      opCreateTaxonomyBlock({ path: { graph_id: graphId }, body, headers })
     )
     return (envelope.result ?? {}) as Record<string, unknown>
   }
 
-  /** Soft-delete a taxonomy (`is_active=false`). */
-  async deleteTaxonomy(graphId: string, taxonomyId: string): Promise<Record<string, unknown>> {
-    const body: DeleteTaxonomyRequest = { taxonomy_id: taxonomyId }
+  /** Update a taxonomy block — add/update/remove elements, structures, associations, or rules. */
+  async updateTaxonomyBlock(
+    graphId: string,
+    body: UpdateTaxonomyBlockRequest
+  ): Promise<Record<string, unknown>> {
     const envelope = await this.callOperation(
-      'Delete taxonomy',
-      opDeleteTaxonomy({ path: { graph_id: graphId }, body })
+      'Update taxonomy block',
+      opUpdateTaxonomyBlock({ path: { graph_id: graphId }, body })
     )
     return (envelope.result ?? {}) as Record<string, unknown>
   }
 
-  /**
-   * Link the graph's entity to a taxonomy (ENTITY_HAS_TAXONOMY edge).
-   * Idempotent — returns existing linkage if already present.
-   */
-  async linkEntityTaxonomy(
+  /** Delete a taxonomy block. Cascades through elements, structures, and associations. */
+  async deleteTaxonomyBlock(
     graphId: string,
-    body: LinkEntityTaxonomyRequest
-  ): Promise<Record<string, unknown>> {
+    body: DeleteTaxonomyBlockRequest
+  ): Promise<{ deleted: boolean }> {
     const envelope = await this.callOperation(
-      'Link entity taxonomy',
-      opLinkEntityTaxonomy({ path: { graph_id: graphId }, body })
+      'Delete taxonomy block',
+      opDeleteTaxonomyBlock({ path: { graph_id: graphId }, body })
     )
-    return (envelope.result ?? {}) as Record<string, unknown>
+    return (envelope.result ?? { deleted: true }) as { deleted: boolean }
   }
 
   /** List elements (CoA accounts, GAAP concepts, etc.) with filters. */
@@ -847,40 +840,6 @@ export class LedgerClient {
     )
   }
 
-  /** Create a new element within a taxonomy (native CoA account, etc.). */
-  async createElement(
-    graphId: string,
-    body: CreateElementRequest
-  ): Promise<Record<string, unknown>> {
-    const envelope = await this.callOperation(
-      'Create element',
-      opCreateElement({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? {}) as Record<string, unknown>
-  }
-
-  /** Update mutable fields on an element. `taxonomy_id` and `source` are immutable. */
-  async updateElement(
-    graphId: string,
-    body: UpdateElementRequest
-  ): Promise<Record<string, unknown>> {
-    const envelope = await this.callOperation(
-      'Update element',
-      opUpdateElement({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? {}) as Record<string, unknown>
-  }
-
-  /** Soft-delete an element (`is_active=false`). */
-  async deleteElement(graphId: string, elementId: string): Promise<Record<string, unknown>> {
-    const body: DeleteElementRequest = { element_id: elementId }
-    const envelope = await this.callOperation(
-      'Delete element',
-      opDeleteElement({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? {}) as Record<string, unknown>
-  }
-
   // ── Structures ──────────────────────────────────────────────────────
 
   /** List reporting structures (IS, BS, CF, schedules) with optional filters. */
@@ -901,62 +860,6 @@ export class LedgerClient {
     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: string, body: CreateStructureRequest): Promise<LedgerMappingInfo> {
-    const envelope = await this.callOperation(
-      'Create structure',
-      opCreateStructure({ path: { graph_id: graphId }, body })
-    )
-    return envelope.result as unknown as LedgerMappingInfo
-  }
-
-  /** Convenience wrapper — create a CoA→GAAP mapping structure. */
-  async createMappingStructure(
-    graphId: string,
-    options?: {
-      name?: string
-      description?: string | null
-      taxonomyId?: string
-    }
-  ): Promise<LedgerMappingInfo> {
-    const body: CreateStructureRequest = {
-      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',
-      opCreateStructure({ path: { graph_id: graphId }, body })
-    )
-    return envelope.result as unknown as LedgerMappingInfo
-  }
-
-  /** Update mutable fields on a structure. `structure_type` is immutable. */
-  async updateStructure(
-    graphId: string,
-    body: UpdateStructureRequest
-  ): Promise<Record<string, unknown>> {
-    const envelope = await this.callOperation(
-      'Update structure',
-      opUpdateStructure({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? {}) as Record<string, unknown>
-  }
-
-  /** Soft-delete a structure (`is_active=false`). */
-  async deleteStructure(graphId: string, structureId: string): Promise<Record<string, unknown>> {
-    const body: DeleteStructureRequest = { structure_id: structureId }
-    const envelope = await this.callOperation(
-      'Delete structure',
-      opDeleteStructure({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? {}) as Record<string, unknown>
-  }
-
   // ── Mappings ────────────────────────────────────────────────────────
 
   /** List active CoA→reporting mapping structures. */
@@ -1036,104 +939,86 @@ export class LedgerClient {
     return { operationId: envelope.operationId, status: envelope.status }
   }
 
-  /** Bulk create associations within a single structure, atomically. */
-  async createAssociations(
-    graphId: string,
-    structureId: string,
-    associations: BulkAssociationItem[]
-  ): Promise<Record<string, unknown>> {
-    const body: BulkCreateAssociationsRequest = { structure_id: structureId, associations }
-    const envelope = await this.callOperation(
-      'Create associations',
-      opCreateAssociations({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? {}) as Record<string, unknown>
-  }
+  // ── Information Blocks ─────────────────────────────────────────────
 
-  /** Update mutable fields on an association (order, weight, confidence). */
-  async updateAssociation(
-    graphId: string,
-    body: UpdateAssociationRequest
-  ): Promise<Record<string, unknown>> {
-    const envelope = await this.callOperation(
-      'Update association',
-      opUpdateAssociation({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? {}) as Record<string, unknown>
-  }
-
-  /** Hard-delete an association (any type: presentation, calculation, mapping). */
-  async deleteAssociation(graphId: string, associationId: string): Promise<{ deleted: boolean }> {
-    const body: DeleteAssociationRequest = { association_id: associationId }
-    const envelope = await this.callOperation(
-      'Delete association',
-      opDeleteAssociation({ path: { graph_id: graphId }, body })
-    )
-    return (envelope.result ?? { deleted: true }) as { deleted: boolean }
-  }
-
-  // ── Schedules ──────────────────────────────────────────────────────
-
-  /** List all schedule structures with metadata. */
-  async listSchedules(graphId: string): Promise<LedgerSchedule[]> {
-    const list = await this.gqlQuery(
+  /**
+   * Fetch an Information Block envelope by id — the generic
+   * cross-block-type read. Returns `null` when the block doesn't exist
+   * (or its type isn't registered). See `information-block.md`.
+   */
+  async getInformationBlock(graphId: string, id: string): Promise<InformationBlock | null> {
+    const block = await this.gqlQuery(
       graphId,
-      ListLedgerSchedulesDocument,
-      undefined,
-      'List schedules',
-      (data) => data.schedules
+      GetInformationBlockDocument,
+      { id },
+      'Get information block',
+      (data) => data.informationBlock ?? null
     )
-    return list?.schedules ?? []
+    return block ?? null
   }
 
-  /** Schedule facts optionally filtered by period window. */
-  async getScheduleFacts(
+  /**
+   * List Information Block envelopes with optional block_type + category
+   * filters. Replaces the old `listSchedules` method — callers use
+   * `{blockType: 'schedule'}` to get the same set of blocks.
+   */
+  async listInformationBlocks(
     graphId: string,
-    structureId: string,
-    options?: { periodStart?: string; periodEnd?: string }
-  ): Promise<LedgerScheduleFact[]> {
-    const facts = await this.gqlQuery(
+    options?: {
+      blockType?: string
+      category?: string
+      limit?: number
+      offset?: number
+    }
+  ): Promise<InformationBlockList> {
+    const blocks = await this.gqlQuery(
       graphId,
-      GetLedgerScheduleFactsDocument,
+      ListInformationBlocksDocument,
       {
-        structureId,
-        periodStart: options?.periodStart ?? null,
-        periodEnd: options?.periodEnd ?? null,
+        blockType: options?.blockType ?? null,
+        category: options?.category ?? null,
+        limit: options?.limit ?? null,
+        offset: options?.offset ?? null,
       },
-      'Get schedule facts',
-      (data) => data.scheduleFacts
+      'List information blocks',
+      (data) => data.informationBlocks
     )
-    return facts?.facts ?? []
+    return blocks ?? []
   }
 
+  // ── Schedules ──────────────────────────────────────────────────────
+
   /** Create a new schedule with pre-generated monthly facts. */
   async createSchedule(graphId: string, options: CreateScheduleOptions): Promise<ScheduleCreated> {
-    const body: CreateScheduleRequest = {
-      name: options.name,
-      element_ids: options.elementIds,
-      period_start: options.periodStart,
-      period_end: options.periodEnd,
-      monthly_amount: options.monthlyAmount,
-      entry_template: {
-        debit_element_id: options.entryTemplate.debitElementId,
-        credit_element_id: options.entryTemplate.creditElementId,
-        entry_type: options.entryTemplate.entryType,
-        memo_template: options.entryTemplate.memoTemplate,
+    const body: CreateInformationBlockRequest = {
+      block_type: 'schedule',
+      payload: {
+        name: options.name,
+        element_ids: options.elementIds,
+        period_start: options.periodStart,
+        period_end: options.periodEnd,
+        monthly_amount: options.monthlyAmount,
+        entry_template: {
+          debit_element_id: options.entryTemplate.debitElementId,
+          credit_element_id: options.entryTemplate.creditElementId,
+          entry_type: options.entryTemplate.entryType,
+          memo_template: options.entryTemplate.memoTemplate,
+        },
+        taxonomy_id: options.taxonomyId,
+        schedule_metadata: options.scheduleMetadata
+          ? {
+              method: options.scheduleMetadata.method,
+              original_amount: options.scheduleMetadata.originalAmount,
+              residual_value: options.scheduleMetadata.residualValue,
+              useful_life_months: options.scheduleMetadata.usefulLifeMonths,
+              asset_element_id: options.scheduleMetadata.assetElementId,
+            }
+          : undefined,
       },
-      taxonomy_id: options.taxonomyId,
-      schedule_metadata: options.scheduleMetadata
-        ? {
-            method: options.scheduleMetadata.method,
-            original_amount: options.scheduleMetadata.originalAmount,
-            residual_value: options.scheduleMetadata.residualValue,
-            useful_life_months: options.scheduleMetadata.usefulLifeMonths,
-            asset_element_id: options.scheduleMetadata.assetElementId,
-          }
-        : undefined,
     }
     const envelope = await this.callOperation(
       'Create schedule',
-      opCreateSchedule({ path: { graph_id: graphId }, body })
+      opCreateInformationBlock({ path: { graph_id: graphId }, body })
     )
     const raw = envelope.result as unknown as RawScheduleCreatedResult
     return {
@@ -1148,21 +1033,29 @@ export class LedgerClient {
   /** Update mutable fields on a schedule (name, entry_template, metadata). */
   async updateSchedule(
     graphId: string,
-    body: UpdateScheduleRequest
+    structureId: string,
+    options: { name?: string }
   ): Promise<Record<string, unknown>> {
+    const body: UpdateInformationBlockRequest = {
+      block_type: 'schedule',
+      payload: { structure_id: structureId, ...options },
+    }
     const envelope = await this.callOperation(
       'Update schedule',
-      opUpdateSchedule({ path: { graph_id: graphId }, body })
+      opUpdateInformationBlock({ path: { graph_id: graphId }, body })
     )
     return (envelope.result ?? {}) as Record<string, unknown>
   }
 
   /** Permanently delete a schedule (cascades through facts + associations). */
   async deleteSchedule(graphId: string, structureId: string): Promise<{ deleted: boolean }> {
-    const body: DeleteScheduleRequest = { structure_id: structureId }
+    const body: DeleteInformationBlockRequest = {
+      block_type: 'schedule',
+      payload: { structure_id: structureId },
+    }
     const envelope = await this.callOperation(
       'Delete schedule',
-      opDeleteSchedule({ path: { graph_id: graphId }, body })
+      opDeleteInformationBlock({ path: { graph_id: graphId }, body })
     )
     return (envelope.result ?? { deleted: true }) as { deleted: boolean }
   }
@@ -1191,6 +1084,30 @@ export class LedgerClient {
     }
   }
 
+  /** Dispose of a schedule asset — post a disposal entry and delete forward facts. */
+  async disposeSchedule(
+    graphId: string,
+    body: DisposeScheduleRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Dispose schedule',
+      opDisposeSchedule({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Evaluate taxonomy rules against facts in a structure. */
+  async evaluateRules(
+    graphId: string,
+    body: EvaluateRulesRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Evaluate rules',
+      opEvaluateRules({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
   // ── Period close ────────────────────────────────────────────────────
 
   /** Close status for all schedules in a fiscal period. */