@robosystems/client 2.31.0 → 2.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -67,6 +67,7 @@ import {
67
67
  previewEventBlock,
68
68
  previewReconciliations,
69
69
  previewReconcilingItem,
70
+ previewSchedule,
70
71
  promoteObligations,
71
72
  proposeConsolidationEntries,
72
73
  rebuildSchedule,
@@ -125,6 +126,7 @@ import type {
125
126
  CreateMappingAssociationOperation,
126
127
  CreatePublishListRequest,
127
128
  CreateReportRequest,
129
+ CreateScheduleArm,
128
130
  CreateTaxonomyBlockRequest,
129
131
  CreateViewRequest,
130
132
  DeleteInformationBlockRequest,
@@ -136,6 +138,7 @@ import type {
136
138
  DeleteTaxonomyBlockResponse,
137
139
  DimensionResponse,
138
140
  EntityTaxonomyResponse,
141
+ EntryTemplateRequest,
139
142
  EvaluateRulesRequest,
140
143
  EvaluateRulesResponse,
141
144
  EventBlockEnvelope,
@@ -156,11 +159,13 @@ import type {
156
159
  LinkEntityTaxonomyRequest,
157
160
  LiveFinancialStatementRequest,
158
161
  LiveFinancialStatementResponse,
162
+ LoanTermsRequest,
159
163
  OperationEnvelope,
160
164
  OwnershipChangeResponse,
161
165
  PreviewConsolidationEntriesResponse,
162
166
  PreviewEventBlockResponse,
163
167
  PreviewReconciliationsRequest,
168
+ PreviewScheduleRequest,
164
169
  PromoteObligationsRequest,
165
170
  PromoteObligationsResponse,
166
171
  ProposeConsolidationEntriesResponse,
@@ -185,6 +190,7 @@ import type {
185
190
  ResolveReconcilingItemRequest,
186
191
  ResolveReconcilingItemResponse,
187
192
  RevokeReportShareResponse,
193
+ ScheduleMetadataRequest,
188
194
  SetAllocationOverrideRequest,
189
195
  SetCloseTargetOperation,
190
196
  SetReconciliationPolicyRequest,
@@ -866,36 +872,264 @@ export interface LedgerReconciliationPolicy {
866
872
  statementCycle: StatementCycle | null
867
873
  }
868
874
 
875
+ export type ScheduleMethod = 'straight_line' | 'custom' | 'effective_interest'
876
+ /** The columns of a loan schedule's amortization table a leg can post. */
877
+ export type ScheduleCurveColumn = 'interest' | 'interest_paid' | 'principal' | 'payment'
878
+ export type ScheduleDayCount = '30/360' | 'actual/365' | 'actual/360'
879
+ export type SchedulePaymentFrequency = 'monthly' | 'quarterly' | 'annual' | 'at_maturity'
880
+
881
+ /** One line of the entry a loan schedule drafts each period. */
882
+ export interface ScheduleLeg {
883
+ elementId: string
884
+ side: 'debit' | 'credit'
885
+ /**
886
+ * The amortization-table column the line takes each period: `interest`
887
+ * (accrued in the period), `interest_paid` (accrued interest settled by
888
+ * the period's payment), `principal` (principal repaid), `payment`
889
+ * (interest_paid + principal).
890
+ */
891
+ amountSource: ScheduleCurveColumn
892
+ }
893
+
894
+ /** The terms a loan schedule's amortization table is computed from. */
895
+ export interface LoanTerms {
896
+ /** Principal drawn, in cents. */
897
+ principal: number
898
+ /** Annual interest rate as a fraction: 0.099 for 9.9%. */
899
+ annualRate: number
900
+ /** The day the principal was drawn (YYYY-MM-DD); falls in the schedule's first month. */
901
+ startDate: string
902
+ /** `30/360` (default), `actual/365`, or `actual/360` (the usual bank line of credit). */
903
+ dayCount?: ScheduleDayCount
904
+ /** How often a payment falls due, applied at the end of the month it falls in. Default monthly. */
905
+ paymentFrequency?: SchedulePaymentFrequency
906
+ /** The first payment's date. Omit for one frequency after the schedule's first month. */
907
+ firstPaymentDate?: string | null
908
+ /**
909
+ * Each scheduled payment in cents, interest included. Omit for the level
910
+ * payment that retires the principal by `maturityDate`, or for the accrued
911
+ * interest when `interestOnly`.
912
+ */
913
+ paymentAmount?: number | null
914
+ /** Payments settle interest only; the principal is due at maturity. */
915
+ interestOnly?: boolean
916
+ /**
917
+ * When the remaining principal is due: repaid in that month, the
918
+ * schedule's last. Omit for a line of credit with no maturity, whose
919
+ * balance carries past the schedule.
920
+ */
921
+ maturityDate?: string | null
922
+ /** Interest is added to the note (a PIK note) rather than accrued apart. */
923
+ capitalizeInterest?: boolean
924
+ /**
925
+ * The liability account the principal is carried in. The schedule states
926
+ * its balance each period, which the schedule reconciliation compares
927
+ * with the ledger.
928
+ */
929
+ noteElementId: string
930
+ /**
931
+ * A current-liability account for the principal due within twelve
932
+ * months. When set, each period's entry also reclasses between it and
933
+ * the note so it holds the next twelve months' principal.
934
+ */
935
+ currentPortionElementId?: string | null
936
+ }
937
+
938
+ export interface ScheduleEntryTemplate {
939
+ /** The account debited: a straight-line or custom schedule's debit; a loan's interest debit leg. */
940
+ debitElementId: string
941
+ /** The account credited: the pair's credit; one of a loan's credit legs. */
942
+ creditElementId: string
943
+ entryType?: LedgerEntryType
944
+ memoTemplate?: string
945
+ /** Auto-generate a reversing entry on the first day of the next period. */
946
+ autoReverse?: boolean
947
+ /** The management dimension members every drafted entry carries, one per axis. */
948
+ dimensionIds?: string[]
949
+ /**
950
+ * The lines of a loan schedule's entry (`method: 'effective_interest'`
951
+ * only), each taking one column of the amortization table; each period's
952
+ * lines must balance. Accrue and pay through the bank: debit Interest
953
+ * Expense and credit Accrued Interest, both `interest`. The schedule
954
+ * settles the payment itself: debit the note `principal`, debit Interest
955
+ * Expense `interest`, credit cash or a due-to `payment`.
956
+ */
957
+ legs?: ScheduleLeg[]
958
+ }
959
+
960
+ export interface ScheduleMetadata {
961
+ /**
962
+ * `straight_line` (default) spreads `monthlyAmount` over the months, the
963
+ * last absorbing rounding; `custom` takes `periodicAmounts`;
964
+ * `effective_interest` is a loan computed from `loanTerms`.
965
+ */
966
+ method?: ScheduleMethod | (string & {})
967
+ /** Cost basis in cents. */
968
+ originalAmount?: number
969
+ /** Salvage value in cents; the schedule expenses `originalAmount` less this. */
970
+ residualValue?: number
971
+ usefulLifeMonths?: number
972
+ /** Balance-sheet asset element for net book value. */
973
+ assetElementId?: string
974
+ /**
975
+ * The day the cost went on the books (YYYY-MM-DD), when that is before
976
+ * the schedule's first period. The schedule reconciliation carries the
977
+ * cost from that day.
978
+ */
979
+ bookedOn?: string
980
+ /**
981
+ * `custom` only: one cents value per month, non-negative, summing to
982
+ * `originalAmount` less `residualValue`.
983
+ */
984
+ periodicAmounts?: number[]
985
+ /** `effective_interest` only. */
986
+ loanTerms?: LoanTerms
987
+ }
988
+
989
+ /**
990
+ * A schedule's definition: what `createSchedule` and `previewSchedule`
991
+ * take, and what `rebuildSchedule` saves back.
992
+ */
869
993
  export interface CreateScheduleOptions {
870
994
  name: string
871
995
  elementIds: string[]
872
996
  periodStart: string
873
997
  periodEnd: string
874
- monthlyAmount: number
875
- entryTemplate: {
876
- debitElementId: string
877
- creditElementId: string
878
- entryType?: LedgerEntryType
879
- memoTemplate?: string
880
- }
998
+ /**
999
+ * Monthly amount in cents. Required for a straight-line schedule; a
1000
+ * custom or loan schedule takes its amounts from its curve.
1001
+ */
1002
+ monthlyAmount?: number
1003
+ entryTemplate: ScheduleEntryTemplate
881
1004
  taxonomyId?: string
882
- scheduleMetadata?: {
883
- method?: string
884
- originalAmount?: number
885
- residualValue?: number
886
- usefulLifeMonths?: number
887
- assetElementId?: string
888
- /**
889
- * The day the cost went on the books (YYYY-MM-DD), when that is before
890
- * the schedule's first period. The schedule reconciliation carries the
891
- * cost from that day.
892
- */
893
- bookedOn?: string
894
- }
1005
+ scheduleMetadata?: ScheduleMetadata
895
1006
  /** The entity whose books the schedule belongs to. Omit for the group parent. */
896
1007
  entityId?: string | null
1008
+ /**
1009
+ * Onboarding watermark: months ending on or before it are history the
1010
+ * schedule records but never drafts. Defaults to the calendar's
1011
+ * closed-through month.
1012
+ */
1013
+ closedThrough?: string
1014
+ }
1015
+
1016
+ export interface PreviewScheduleOptions extends CreateScheduleOptions {
1017
+ /** The schedule this definition would replace, when editing or recreating one. */
1018
+ replacesStructureId?: string | null
1019
+ }
1020
+
1021
+ export interface RebuildScheduleOptions {
1022
+ idempotencyKey?: string
1023
+ periodStart?: string
1024
+ periodEnd?: string
1025
+ monthlyAmount?: number
1026
+ /** A new entry template, replacing the stored one whole. */
1027
+ entryTemplate?: ScheduleEntryTemplate
1028
+ /** The schedule_metadata fields to change; the rest keep their stored values. */
1029
+ scheduleMetadata?: ScheduleMetadata
1030
+ }
1031
+
1032
+ /** One period of a previewed schedule: the balance it carries, and what moves it. */
1033
+ export interface ScheduleRollForwardPeriod {
1034
+ periodStart: string
1035
+ periodEnd: string
1036
+ opening: number
1037
+ /** What the period recognizes: the entry's debit amount. */
1038
+ amount: number
1039
+ closing: number
1040
+ /** `historical` for a month already in the books' history; `in_scope` for one a close drafts. */
1041
+ scope: 'historical' | 'in_scope'
1042
+ /** Loan schedules only. */
1043
+ interest: number | null
1044
+ payment: number | null
1045
+ principal: number | null
1046
+ currentPortion: number | null
1047
+ }
1048
+
1049
+ /** What an existing schedule's entries mean for replacing it. */
1050
+ export interface ScheduleReplacement {
1051
+ structureId: string
1052
+ name: string
1053
+ postedEntryCount: number
1054
+ /** The months (YYYY-MM) its posted entries are in. */
1055
+ postedPeriods: string[]
1056
+ draftEntryCount: number
1057
+ /** `rebuild` while nothing has posted; `terminate_and_succeed` once an entry has. */
1058
+ path: 'rebuild' | 'terminate_and_succeed'
1059
+ }
1060
+
1061
+ /** Result of `previewSchedule`: a generated schedule nobody kept. */
1062
+ export interface SchedulePreview {
1063
+ /**
1064
+ * The envelope create would leave, in the operation's own snake_case
1065
+ * shape; its ids are provisional. `artifact.mechanics` reads the
1066
+ * definition back.
1067
+ */
1068
+ envelope: InformationBlockEnvelope
1069
+ rollForward: ScheduleRollForwardPeriod[]
1070
+ /** Another active schedule already posting the same accounts over the same months. */
1071
+ warnings: string[]
1072
+ replaces: ScheduleReplacement | null
897
1073
  }
898
1074
 
1075
+ const toScheduleLeg = (leg: ScheduleLeg) => ({
1076
+ element_id: leg.elementId,
1077
+ side: leg.side,
1078
+ amount_source: leg.amountSource,
1079
+ })
1080
+
1081
+ const toEntryTemplate = (template: ScheduleEntryTemplate): EntryTemplateRequest => ({
1082
+ debit_element_id: template.debitElementId,
1083
+ credit_element_id: template.creditElementId,
1084
+ entry_type: template.entryType,
1085
+ memo_template: template.memoTemplate,
1086
+ auto_reverse: template.autoReverse,
1087
+ dimension_ids: template.dimensionIds,
1088
+ legs: template.legs?.map(toScheduleLeg),
1089
+ })
1090
+
1091
+ const toLoanTerms = (terms: LoanTerms): LoanTermsRequest => ({
1092
+ principal: terms.principal,
1093
+ annual_rate: terms.annualRate,
1094
+ start_date: terms.startDate,
1095
+ day_count: terms.dayCount,
1096
+ payment_frequency: terms.paymentFrequency,
1097
+ first_payment_date: terms.firstPaymentDate,
1098
+ payment_amount: terms.paymentAmount,
1099
+ interest_only: terms.interestOnly,
1100
+ maturity_date: terms.maturityDate,
1101
+ capitalize_interest: terms.capitalizeInterest,
1102
+ note_element_id: terms.noteElementId,
1103
+ current_portion_element_id: terms.currentPortionElementId,
1104
+ })
1105
+
1106
+ const toScheduleMetadata = (metadata: ScheduleMetadata): ScheduleMetadataRequest => ({
1107
+ method: metadata.method,
1108
+ original_amount: metadata.originalAmount,
1109
+ residual_value: metadata.residualValue,
1110
+ useful_life_months: metadata.usefulLifeMonths,
1111
+ asset_element_id: metadata.assetElementId,
1112
+ booked_on: metadata.bookedOn,
1113
+ periodic_amounts: metadata.periodicAmounts,
1114
+ loan_terms: metadata.loanTerms ? toLoanTerms(metadata.loanTerms) : undefined,
1115
+ })
1116
+
1117
+ /** The definition as the schedule operations take it. */
1118
+ const toScheduleDefinition = (options: CreateScheduleOptions): CreateScheduleArm['payload'] => ({
1119
+ name: options.name,
1120
+ element_ids: options.elementIds,
1121
+ period_start: options.periodStart,
1122
+ period_end: options.periodEnd,
1123
+ monthly_amount: options.monthlyAmount,
1124
+ entry_template: toEntryTemplate(options.entryTemplate),
1125
+ taxonomy_id: options.taxonomyId,
1126
+ ...(options.entityId ? { entity_id: options.entityId } : {}),
1127
+ closed_through: options.closedThrough,
1128
+ schedule_metadata: options.scheduleMetadata
1129
+ ? toScheduleMetadata(options.scheduleMetadata)
1130
+ : undefined,
1131
+ })
1132
+
899
1133
  export interface JournalEntryLineItem {
900
1134
  elementId: string
901
1135
  debitAmount?: number
@@ -2102,31 +2336,7 @@ export class LedgerClient {
2102
2336
  ): Promise<ScheduleBlockCreated> {
2103
2337
  const body: CreateInformationBlockRequest = {
2104
2338
  block_type: 'schedule',
2105
- payload: {
2106
- name: options.name,
2107
- element_ids: options.elementIds,
2108
- period_start: options.periodStart,
2109
- period_end: options.periodEnd,
2110
- monthly_amount: options.monthlyAmount,
2111
- entry_template: {
2112
- debit_element_id: options.entryTemplate.debitElementId,
2113
- credit_element_id: options.entryTemplate.creditElementId,
2114
- entry_type: options.entryTemplate.entryType,
2115
- memo_template: options.entryTemplate.memoTemplate,
2116
- },
2117
- taxonomy_id: options.taxonomyId,
2118
- ...(options.entityId ? { entity_id: options.entityId } : {}),
2119
- schedule_metadata: options.scheduleMetadata
2120
- ? {
2121
- method: options.scheduleMetadata.method,
2122
- original_amount: options.scheduleMetadata.originalAmount,
2123
- residual_value: options.scheduleMetadata.residualValue,
2124
- useful_life_months: options.scheduleMetadata.usefulLifeMonths,
2125
- asset_element_id: options.scheduleMetadata.assetElementId,
2126
- booked_on: options.scheduleMetadata.bookedOn,
2127
- }
2128
- : undefined,
2129
- },
2339
+ payload: toScheduleDefinition(options),
2130
2340
  }
2131
2341
  const envelope = await this.callOperation('Create schedule', (o) =>
2132
2342
  createInformationBlock({ ...o, path: { graph_id: graphId }, body })
@@ -2147,6 +2357,61 @@ export class LedgerClient {
2147
2357
  }
2148
2358
  }
2149
2359
 
2360
+ /**
2361
+ * Generate a schedule from a definition without keeping it: the same
2362
+ * generator and guards as `createSchedule`, run and rolled back. Returns
2363
+ * the envelope create would leave (its ids provisional), the roll-forward
2364
+ * (the balance the schedule carries period by period; a loan's note, with
2365
+ * its interest, payment, principal and current portion), and warnings
2366
+ * naming any active schedule already posting the same accounts in the
2367
+ * same months. A definition create would refuse (a roll-forward that
2368
+ * climbs where it should fall, legs that do not balance) is refused here
2369
+ * with the period that breaks. With `replacesStructureId`, `replaces`
2370
+ * says what the schedule being edited or recreated has posted, by month,
2371
+ * and the path the change takes: `rebuild` (save through
2372
+ * `rebuildSchedule`) while nothing has posted, `terminate_and_succeed`
2373
+ * after.
2374
+ */
2375
+ async previewSchedule(
2376
+ graphId: string,
2377
+ options: PreviewScheduleOptions
2378
+ ): Promise<SchedulePreview> {
2379
+ const body: PreviewScheduleRequest = {
2380
+ ...toScheduleDefinition(options),
2381
+ replaces_structure_id: options.replacesStructureId ?? undefined,
2382
+ }
2383
+ const envelope = await this.callOperation('Preview schedule', (o) =>
2384
+ previewSchedule({ ...o, path: { graph_id: graphId }, body })
2385
+ )
2386
+ const raw = this.requireResult('Preview schedule', envelope.result)
2387
+ return {
2388
+ envelope: raw.envelope,
2389
+ rollForward: (raw.roll_forward ?? []).map((row) => ({
2390
+ periodStart: row.period_start,
2391
+ periodEnd: row.period_end,
2392
+ opening: row.opening,
2393
+ amount: row.amount,
2394
+ closing: row.closing,
2395
+ scope: row.scope,
2396
+ interest: row.interest ?? null,
2397
+ payment: row.payment ?? null,
2398
+ principal: row.principal ?? null,
2399
+ currentPortion: row.current_portion ?? null,
2400
+ })),
2401
+ warnings: raw.warnings ?? [],
2402
+ replaces: raw.replaces
2403
+ ? {
2404
+ structureId: raw.replaces.structure_id,
2405
+ name: raw.replaces.name,
2406
+ postedEntryCount: raw.replaces.posted_entry_count,
2407
+ postedPeriods: raw.replaces.posted_periods ?? [],
2408
+ draftEntryCount: raw.replaces.draft_entry_count ?? 0,
2409
+ path: raw.replaces.path,
2410
+ }
2411
+ : null,
2412
+ }
2413
+ }
2414
+
2150
2415
  /**
2151
2416
  * Rename a schedule. For other block fields use `updateInformationBlock`
2152
2417
  * with a `schedule` payload.
@@ -2192,15 +2457,33 @@ export class LedgerClient {
2192
2457
  * a rebuild re-scopes the schedule to today's close state. Use this to
2193
2458
  * pick up a fixed generator without orphaning obligations.
2194
2459
  *
2460
+ * It is also how an edit is saved while nothing has posted: the
2461
+ * definition fields on `options` (`periodStart`, `periodEnd`,
2462
+ * `monthlyAmount`, `entryTemplate` replacing the stored one whole,
2463
+ * `scheduleMetadata` for only the fields named) replace the stored
2464
+ * definition before it regenerates, as the schedule's envelope reads them
2465
+ * back (`artifact.mechanics`). Omitted fields keep their stored values.
2466
+ * Refused once an entry has posted; `previewSchedule` with
2467
+ * `replacesStructureId` says which path an edit takes.
2468
+ *
2195
2469
  * Returns the {@link ScheduleCreated} rebuild summary (periods, facts,
2196
2470
  * rule results) — richer than `createSchedule`'s {@link ScheduleBlockCreated}.
2197
2471
  */
2198
2472
  async rebuildSchedule(
2199
2473
  graphId: string,
2200
2474
  structureId: string,
2201
- options?: { idempotencyKey?: string }
2475
+ options?: RebuildScheduleOptions
2202
2476
  ): Promise<ScheduleCreated> {
2203
- const body: RebuildScheduleRequest = { structure_id: structureId }
2477
+ const body: RebuildScheduleRequest = {
2478
+ structure_id: structureId,
2479
+ period_start: options?.periodStart,
2480
+ period_end: options?.periodEnd,
2481
+ monthly_amount: options?.monthlyAmount,
2482
+ entry_template: options?.entryTemplate ? toEntryTemplate(options.entryTemplate) : undefined,
2483
+ schedule_metadata: options?.scheduleMetadata
2484
+ ? toScheduleMetadata(options.scheduleMetadata)
2485
+ : undefined,
2486
+ }
2204
2487
  const envelope = await this.callOperation('Rebuild schedule', (o) =>
2205
2488
  rebuildSchedule({
2206
2489
  ...withIdempotencyKey(o, options?.idempotencyKey),