@robosystems/client 0.5.8 → 0.5.9

package/types.gen.ts

@@ -379,6 +379,129 @@ export type AvailableGraphTiersResponse = {
     tiers: Array<GraphTierInfo>;
 };
 
+/**
+ * BackfillPeriodOutcome
+ *
+ * Per-month result of a plan-history backfill pass.
+ */
+export type BackfillPeriodOutcome = {
+    /**
+     * Period
+     *
+     * The month, in YYYY-MM
+     */
+    period: string;
+    /**
+     * Status
+     *
+     * stamped: reopen → reclose completed. skipped_drafts: the month holds draft entries the backfill refuses to post — review via list-period-drafts, then close-period or re-run. failed: the reclose raised; processing halted (see detail).
+     */
+    status: string;
+    /**
+     * Statements Stamped
+     *
+     * Whether the reclose stamped canonical statement FactSets. False with a statement_stamp_note soft-skip when reporting isn't set up.
+     */
+    statements_stamped?: boolean;
+    /**
+     * Statement Stamp Note
+     *
+     * Soft-skip reason when statements_stamped is false
+     */
+    statement_stamp_note?: string | null;
+    /**
+     * Statement Rule Summary
+     *
+     * Statement-rule verification tally for the month's stamped sets (pass/fail/error/skipped); None when no rules ran.
+     */
+    statement_rule_summary?: {
+        [key: string]: number;
+    } | null;
+    /**
+     * Detail
+     *
+     * Human-readable detail for skipped/failed months
+     */
+    detail?: string | null;
+};
+
+/**
+ * BackfillPlanHistoryOperation
+ *
+ * Compile monthly statement history behind the close boundary.
+ */
+export type BackfillPlanHistoryOperation = {
+    /**
+     * Start Period
+     *
+     * YYYY-MM period to backfill from. Clamped to the earliest month with ledger data; defaults to that month when omitted. Must be on or before `closed_through`.
+     */
+    start_period?: string | null;
+    /**
+     * Max Periods
+     *
+     * Maximum months to restamp in this call. Each month runs a full reopen → reclose cycle; keep chunks modest and loop on `remaining_periods`.
+     */
+    max_periods?: number;
+    /**
+     * Allow Stale Sync
+     *
+     * Override the sync-currency gate on each reclose. Historical months predate the last sync in the normal case, so this is rarely needed.
+     */
+    allow_stale_sync?: boolean;
+    /**
+     * Note
+     *
+     * Free-form note attached to each close audit event
+     */
+    note?: string | null;
+};
+
+/**
+ * BackfillPlanHistoryResponse
+ *
+ * Response from one chunked plan-history backfill call.
+ */
+export type BackfillPlanHistoryResponse = {
+    fiscal_calendar: FiscalCalendarResponse;
+    /**
+     * Earliest Available Period
+     *
+     * First month with ledger data — the hard floor for backfill
+     */
+    earliest_available_period: string;
+    /**
+     * Effective Start Period
+     *
+     * The start actually used after clamping to earliest_available_period
+     */
+    effective_start_period: string;
+    /**
+     * Closed Through
+     *
+     * The close boundary the backfill runs up to (inclusive)
+     */
+    closed_through: string;
+    /**
+     * Period Rows Created
+     *
+     * FiscalPeriod rows seeded (baseline-closed) for months the calendar didn't cover yet
+     */
+    period_rows_created?: number;
+    /**
+     * Processed
+     *
+     * Months this call attempted, oldest first
+     */
+    processed?: Array<BackfillPeriodOutcome>;
+    /**
+     * Remaining Periods
+     *
+     * Months still lacking canonical statement sets that this call did not attempt (beyond max_periods, or after a failure halt). Loop until empty.
+     */
+    remaining_periods?: Array<string>;
+};
+
 /**
  * BackupCreateRequest
  *
@@ -1230,6 +1353,34 @@ export type ClosePeriodResponse = {
      * ids of schedule Structures whose rules were evaluated during the close. Pairs with rule_summary.
      */
     evaluated_structure_ids?: Array<string>;
+    /**
+     * Statements Stamped
+     *
+     * Whether the close stamped the period's canonical statement FactSets (the close-time pivot). False when the tenant hasn't set up reporting yet — see statement_stamp_note.
+     */
+    statements_stamped?: boolean;
+    /**
+     * Statement Stamp Note
+     *
+     * Soft-skip reason when statements_stamped is false: no_coa_mapping | no_entity | no_statement_structures | no_taxonomy.
+     */
+    statement_stamp_note?: string | null;
+    /**
+     * Stamped Statement Sets
+     *
+     * structure_id -> fact_set_id for every canonical statement FactSet minted by this close (report_id NULL; replaced on reclose).
+     */
+    stamped_statement_sets?: {
+        [key: string]: string;
+    };
+    /**
+     * Statement Rule Summary
+     *
+     * Aggregated statement-rule verification outcome across the stamped structures — keys: pass/fail/error/skipped. None when no statement rules exist. Distinct from rule_summary (the schedule-rule pass).
+     */
+    statement_rule_summary?: {
+        [key: string]: number;
+    } | null;
 };
 
 /**
@@ -2199,6 +2350,12 @@ export type CreateForecastRequest = {
      * Lever assertions — at least one.
      */
     levers: Array<LeverAssertionRequest>;
+    /**
+     * Line Assertions
+     *
+     * Direct statement-line assertions (manual overrides). Each names a calc-DAG leaf and wins over driver rules and carry-forward for the months it asserts.
+     */
+    line_assertions?: Array<LineAssertionRequest>;
     /**
      * Entity Id
      *
@@ -3977,6 +4134,12 @@ export type ElementLite = {
      * Value-domain vocabulary (monetary | ratio | percent | multiple | days | string | …). None means untyped; fall back to is_monetary.
      */
     item_type?: string | null;
+    /**
+     * Documentation
+     *
+     * The element's documentation-role label — the catalog's authoritative value semantics (e.g. whether a percent driver is a growth rate or a rate-on-base fraction). None when the element carries no documentation label.
+     */
+    documentation?: string | null;
 };
 
 /**
@@ -5130,6 +5293,12 @@ export type ForecastMechanics = {
      * Expanded lever assertions (authoring order).
      */
     levers: Array<LeverAssertionLite>;
+    /**
+     * Line Assertions
+     *
+     * Direct statement-line assertions (authoring order) — manual overrides that win over driver rules and carry-forward for the months they name.
+     */
+    line_assertions?: Array<LineAssertionLite>;
     /**
      * Computed Months
      *
@@ -7090,13 +7259,21 @@ export type LeverAssertionLite = {
  * One lever's asserted values for the scenario.
  *
  * ``qname`` must resolve to an ``rs-driver:*`` catalog element (the
- * create handler rejects anything else). Value conventions follow the
- * catalog: percent levers are decimals per month (0.03 = 3%/month),
- * days levers are day counts.
+ * create handler rejects anything else). Each lever's value semantics
+ * are defined by its catalog element's documentation — surfaced as
+ * ``documentation`` on the elements bundled in the forecast block's
+ * envelope (``get-information-block``). Percent levers are decimals but
+ * their *meaning* varies by lever: growth levers are month-over-month
+ * rates (``RevenueGrowthRate`` 0.03 = +3%/month, compounding), while
+ * rate-on-base levers are fractions of the same month's base
+ * (``CostOfRevenueRate`` 0.62 = cost of revenue at 62% of that month's
+ * revenues — not a growth rate). Days levers (``DaysSalesOutstanding``,
+ * ``DaysPayableOutstanding``) are day counts.
  *
  * ``value`` is a uniform fill across the whole horizon;
  * ``values_by_period`` overrides individual months (``"YYYY-MM"``
- * keys). At least one of the two must be provided. Months covered by
+ * keys) — e.g. a margin-compression ramp asserts a different rate each
+ * month. At least one of the two must be provided. Months covered by
  * neither carry no assertion — the lever's rule is inactive for that
  * month and its target falls to the engine's carry-forward default.
  */
@@ -7123,6 +7300,108 @@ export type LeverAssertionRequest = {
     } | null;
 };
 
+/**
+ * LineAssertionLite
+ *
+ * One statement line's persisted direct assertion inside
+ * ``ForecastMechanics``.
+ *
+ * The manual-override sibling of :class:`LeverAssertionLite`: a lever
+ * asserts a *driver* whose rule derives a line; a line assertion pins
+ * the **line itself** (a calc-DAG leaf) to typed values for the months
+ * it names — winning over driver rules and carry-forward for exactly
+ * those months (a displaced rule surfaces in the compute response's
+ * ``skipped`` list). Subtotals stay calc-DAG-derived, so a manual line
+ * still articulates through RollUps, RE, balancing cash, and derived
+ * CF, and stays verification-gated.
+ *
+ * Same persistence doctrine as levers: values are duplicated as
+ * authored facts in the scenario's lever FactSet (facts are what
+ * ``compute-forecast`` binds); this mechanics copy is the
+ * operator-legible round-trip shape.
+ */
+export type LineAssertionLite = {
+    /**
+     * Qname
+     *
+     * Asserted statement-leaf qname.
+     */
+    qname: string;
+    /**
+     * Element Id
+     *
+     * Resolved tenant element id.
+     */
+    element_id: string;
+    /**
+     * Item Type
+     *
+     * Format family from the element (monetary | ...).
+     */
+    item_type?: string | null;
+    /**
+     * Period Type
+     *
+     * The element's period type — duration assertions pin IS lines; instant assertions pin BS lines through the roll.
+     */
+    period_type?: string;
+    /**
+     * Values By Period
+     *
+     * Expanded per-month assertions keyed by ``YYYY-MM``.
+     */
+    values_by_period: {
+        [key: string]: number;
+    };
+};
+
+/**
+ * LineAssertionRequest
+ *
+ * One statement line's directly asserted values for the scenario.
+ *
+ * The manual-override half of the authored surface: where a lever
+ * asserts a *driver* (growth %, DSO) whose rule derives the line, a
+ * line assertion asserts the **line itself** — an rs-gaap (or tenant
+ * extension) statement leaf pinned to typed values for the months it
+ * names. Assertions win over driver rules and carry-forward for those
+ * months (a displaced rule lands in ``skipped``, legibly); months the
+ * assertion doesn't name keep the engine's normal derivation.
+ *
+ * **Leaves only** — subtotals stay calc-DAG-derived, so a manually set
+ * line still articulates through RollUps, RE, balancing cash, and the
+ * derived CF, and stays verification-gated (the whole pitch vs a
+ * spreadsheet cell). The create handler rejects calc-parent qnames.
+ *
+ * Value/period grammar is identical to levers: ``value`` is a uniform
+ * fill across the horizon, ``values_by_period`` overrides individual
+ * months. The canonical uses: zero out a base-month one-off so
+ * carry-forward stops replicating it, or hold a line at a known budget
+ * number no driver models.
+ */
+export type LineAssertionRequest = {
+    /**
+     * Qname
+     *
+     * QName of the statement leaf to assert (e.g. ``rs-gaap:NonoperatingIncomeExpense``). Must be a calc-DAG leaf; rs-driver concepts belong in ``levers``.
+     */
+    qname: string;
+    /**
+     * Value
+     *
+     * Uniform value asserted for every month of the horizon.
+     */
+    value?: number | null;
+    /**
+     * Values By Period
+     *
+     * Per-month overrides keyed by ``YYYY-MM``. Wins over ``value`` for the months it names.
+     */
+    values_by_period?: {
+        [key: string]: number;
+    } | null;
+};
+
 /**
  * LineItemMetadataPredicate
  *
@@ -7905,6 +8184,52 @@ export type OperationEnvelopeAssociationResponse = {
     idempotentReplay?: boolean;
 };
 
+/**
+ * OperationEnvelope[BackfillPlanHistoryResponse]
+ */
+export type OperationEnvelopeBackfillPlanHistoryResponse = {
+    /**
+     * Operation
+     *
+     * Kebab-case operation name
+     */
+    operation: string;
+    /**
+     * Operationid
+     *
+     * op_-prefixed ULID for audit and SSE correlation
+     */
+    operationId: string;
+    /**
+     * Status
+     *
+     * Operation lifecycle state
+     */
+    status: 'completed' | 'pending' | 'failed';
+    /**
+     * Command-specific result payload
+     */
+    result?: BackfillPlanHistoryResponse | null;
+    /**
+     * At
+     *
+     * ISO-8601 UTC timestamp
+     */
+    at: string;
+    /**
+     * Createdby
+     *
+     * User ID that initiated the operation (null for legacy callers)
+     */
+    createdBy?: string | null;
+    /**
+     * Idempotentreplay
+     *
+     * True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.
+     */
+    idempotentReplay?: boolean;
+};
+
 /**
  * OperationEnvelope[BindTextBlockResponse]
  */
@@ -14262,11 +14587,13 @@ export type UpdateEventHandlerRequest = {
  *
  * Update a forecast block in place.
  *
- * Mutable: name, scenario_kind, horizon_months, base_period, levers.
- * ``levers`` is a **full replace** when provided (partial lever edits
- * would make the asserted set ambiguous). Updating does NOT recompute —
- * previously computed scenario months go stale until the next
- * ``compute-forecast`` run (the compute-metrics drift semantics).
+ * Mutable: name, scenario_kind, horizon_months, base_period, levers,
+ * line_assertions. ``levers`` and ``line_assertions`` are each a
+ * **full replace** when provided (partial edits would make the asserted
+ * set ambiguous); replacing one leaves the other as stored. Updating
+ * does NOT recompute — previously computed scenario months go stale
+ * until the next ``compute-forecast`` run (the compute-metrics drift
+ * semantics).
  */
 export type UpdateForecastRequest = {
     /**
@@ -14297,6 +14624,12 @@ export type UpdateForecastRequest = {
      * Full replacement of the lever set when provided.
      */
     levers?: Array<LeverAssertionRequest> | null;
+    /**
+     * Line Assertions
+     *
+     * Full replacement of the line-assertion set when provided. Pass an empty list to clear every assertion.
+     */
+    line_assertions?: Array<LineAssertionRequest> | null;
 };
 
 /**
@@ -15332,7 +15665,7 @@ export type UpdateForecastArm = {
      */
     block_type: 'forecast';
     /**
-     * Forecast update payload.
+     * Forecast update payload. Updating does NOT recompute — lever, horizon, or base-period changes leave the scenario's computed months stale until the next `compute-forecast` run.
      */
     payload: UpdateForecastRequest;
 };
@@ -24045,6 +24378,70 @@ export type ReopenPeriodResponses = {
 
 export type ReopenPeriodResponse = ReopenPeriodResponses[keyof ReopenPeriodResponses];
 
+export type BackfillPlanHistoryData = {
+    body: BackfillPlanHistoryOperation;
+    headers?: {
+        /**
+         * Idempotency-Key
+         */
+        'Idempotency-Key'?: string | null;
+    };
+    path: {
+        /**
+         * Graph Id
+         */
+        graph_id: string;
+    };
+    query?: never;
+    url: '/extensions/roboledger/{graph_id}/operations/backfill-plan-history';
+};
+
+export type BackfillPlanHistoryErrors = {
+    /**
+     * Invalid request
+     */
+    400: ErrorResponse;
+    /**
+     * Authentication required
+     */
+    401: ErrorResponse;
+    /**
+     * Access denied
+     */
+    403: ErrorResponse;
+    /**
+     * Resource not found
+     */
+    404: ErrorResponse;
+    /**
+     * Idempotency-Key conflict — key reused with different body
+     */
+    409: ErrorResponse;
+    /**
+     * Validation error
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+    /**
+     * Internal server error
+     */
+    500: ErrorResponse;
+};
+
+export type BackfillPlanHistoryError = BackfillPlanHistoryErrors[keyof BackfillPlanHistoryErrors];
+
+export type BackfillPlanHistoryResponses = {
+    /**
+     * Successful Response
+     */
+    200: OperationEnvelopeBackfillPlanHistoryResponse;
+};
+
+export type BackfillPlanHistoryResponse2 = BackfillPlanHistoryResponses[keyof BackfillPlanHistoryResponses];
+
 export type CreateReportData = {
     body: CreateReportRequest;
     headers?: {