@robosystems/client 2.9.1 → 2.10.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.
@@ -263,7 +263,7 @@ export type AssertMetricsRequest = {
263
263
  /**
264
264
  * Entity Id
265
265
  *
266
- * Entity to assert for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
266
+ * The entity the asserted values belong to, by id. Omit for the group parent.
267
267
  */
268
268
  entity_id?: string | null;
269
269
  /**
@@ -1141,7 +1141,7 @@ export type BindTextBlockRequest = {
1141
1141
  /**
1142
1142
  * Entity Id
1143
1143
  *
1144
- * Entity the fact belongs to; defaults to the primary entity.
1144
+ * Entity the fact belongs to, by id; omit for the group parent.
1145
1145
  */
1146
1146
  entity_id?: string | null;
1147
1147
  };
@@ -1366,7 +1366,7 @@ export type ChangeReportingStyleRequest = {
1366
1366
  /**
1367
1367
  * Entity Id
1368
1368
  *
1369
- * Target entity. Omit to target the graph's primary (earliest-created) entity — the single-entity default.
1369
+ * The entity whose style to change, by id. Omit for the group parent.
1370
1370
  */
1371
1371
  entity_id?: string | null;
1372
1372
  };
@@ -1738,6 +1738,32 @@ export type ClosePeriodResponse = {
1738
1738
  * 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.
1739
1739
  */
1740
1740
  statements_stamped?: boolean;
1741
+ /**
1742
+ * Shadow
1743
+ *
1744
+ * True when the close ran in shadow (the QuickBooks connection's write_policy is 'shadow'): nothing was written to QuickBooks, nothing posted, the in-window drafts were shadowed, and the gates that would have blocked the close are in gate_findings.
1745
+ */
1746
+ shadow?: boolean;
1747
+ /**
1748
+ * Entries Shadowed
1749
+ *
1750
+ * Drafts a shadow close took as expectations (status 'shadowed') instead of posting. Always 0 outside shadow.
1751
+ */
1752
+ entries_shadowed?: number;
1753
+ /**
1754
+ * Gate Findings
1755
+ *
1756
+ * Blocker codes a shadow close recorded instead of enforcing: sync_stale, pending_obligations, stranded_obligations, reconciling_items, unposted_source_events, unreconciled_accounts. Empty outside shadow.
1757
+ */
1758
+ gate_findings?: Array<string>;
1759
+ /**
1760
+ * Gate Finding Counts
1761
+ *
1762
+ * Each finding's size: days stale for sync_stale, a count for the rest.
1763
+ */
1764
+ gate_finding_counts?: {
1765
+ [key: string]: number;
1766
+ };
1741
1767
  /**
1742
1768
  * Statement Stamp Note
1743
1769
  *
@@ -1888,7 +1914,7 @@ export type ComputeMetricsRequest = {
1888
1914
  /**
1889
1915
  * Entity Id
1890
1916
  *
1891
- * Entity to compute for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
1917
+ * The entity whose metrics to compute, by id. Omit for the group parent.
1892
1918
  */
1893
1919
  entity_id?: string | null;
1894
1920
  /**
@@ -2891,7 +2917,7 @@ export type CreateForecastRequest = {
2891
2917
  /**
2892
2918
  * Entity Id
2893
2919
  *
2894
- * Entity the scenario belongs to. Defaults to the graph's earliest-created entity (single-entity convention).
2920
+ * The entity the scenario belongs to, by id: its history and its computed months are that entity's books. Omit for the group parent.
2895
2921
  */
2896
2922
  entity_id?: string | null;
2897
2923
  };
@@ -3220,6 +3246,12 @@ export type CreateScheduleRequest = {
3220
3246
  * Schedule name
3221
3247
  */
3222
3248
  name: string;
3249
+ /**
3250
+ * Entity Id
3251
+ *
3252
+ * The entity whose books the schedule belongs to, by id. Omit for the group parent. Its facts, obligations and closing entries land in that entity's books, against that entity's own accounts.
3253
+ */
3254
+ entity_id?: string | null;
3223
3255
  /**
3224
3256
  * Taxonomy Id
3225
3257
  *
@@ -7518,6 +7550,12 @@ export type InformationBlockEnvelope = {
7518
7550
  * Qname of the named Disclosure this block corresponds to (e.g., 'disclosures:BalanceSheet'), when an inbound reportedDisclosure-requiresDisclosure arc identifies one. Null for tenant-authored blocks without a Disclosure mapping.
7519
7551
  */
7520
7552
  disclosure_id?: string | null;
7553
+ /**
7554
+ * Entity Id
7555
+ *
7556
+ * The entity whose books the envelope reads. A schedule, reconciliation or forecast is one entity's own and always reads its owner's; a block shared by the group (statements, metrics) reads the entity asked for, else the group parent. Null on the library and on a graph with no entity yet.
7557
+ */
7558
+ entity_id?: string | null;
7521
7559
  information_model: InformationModelResponse;
7522
7560
  artifact: ArtifactResponse;
7523
7561
  /**
@@ -9021,7 +9059,7 @@ export type LinkBankAccountResponse = {
9021
9059
  /**
9022
9060
  * Changed
9023
9061
  *
9024
- * False when the link already stood.
9062
+ * False when the link already stood and no line moved.
9025
9063
  */
9026
9064
  changed?: boolean;
9027
9065
  };
@@ -9472,8 +9510,9 @@ export type MemoryRecord = {
9472
9510
  *
9473
9511
  * Mercury bank-feed connection configuration.
9474
9512
  *
9475
- * A bank feed is native accounting: the graph must already have a chart of
9476
- * accounts and no live QuickBooks connection. Over OAuth (the hosted
9513
+ * A bank feed is native accounting: the entity its accounts land on must
9514
+ * already have a chart of accounts and must not be the one QuickBooks keeps
9515
+ * (the group parent, while QuickBooks is connected). Over OAuth (the hosted
9477
9516
  * default) the connection is created `pending_oauth` and activated by the
9478
9517
  * callback. `api_key` — a personal **read-only** Mercury token — connects
9479
9518
  * at once without a browser round-trip, but only on deployments that turn
@@ -17177,9 +17216,9 @@ export type SetWritePolicyRequest = {
17177
17216
  /**
17178
17217
  * Write Policy
17179
17218
  *
17180
- * 'native' = RoboSystems authoritative, no write-back; 'qb_authoritative' = QuickBooks authoritative, entries publish to QB.
17219
+ * 'qb_authoritative' = QuickBooks authoritative, entries publish to QB; 'shadow' = QuickBooks authoritative and RoboSystems only observes: nothing is written to QuickBooks, the close posts nothing locally, its drafts become shadowed expectations and its gates are findings. 'native', books kept in RoboSystems with no write-back, is what disconnecting or severing leaves, not a choice for a live connection.
17181
17220
  */
17182
- write_policy: 'native' | 'qb_authoritative';
17221
+ write_policy: 'qb_authoritative' | 'shadow';
17183
17222
  };
17184
17223
  /**
17185
17224
  * ShareReportOperation
package/sdk/types.gen.ts CHANGED
@@ -273,7 +273,7 @@ export type AssertMetricsRequest = {
273
273
  /**
274
274
  * Entity Id
275
275
  *
276
- * Entity to assert for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
276
+ * The entity the asserted values belong to, by id. Omit for the group parent.
277
277
  */
278
278
  entity_id?: string | null;
279
279
  /**
@@ -1172,7 +1172,7 @@ export type BindTextBlockRequest = {
1172
1172
  /**
1173
1173
  * Entity Id
1174
1174
  *
1175
- * Entity the fact belongs to; defaults to the primary entity.
1175
+ * Entity the fact belongs to, by id; omit for the group parent.
1176
1176
  */
1177
1177
  entity_id?: string | null;
1178
1178
  };
@@ -1404,7 +1404,7 @@ export type ChangeReportingStyleRequest = {
1404
1404
  /**
1405
1405
  * Entity Id
1406
1406
  *
1407
- * Target entity. Omit to target the graph's primary (earliest-created) entity — the single-entity default.
1407
+ * The entity whose style to change, by id. Omit for the group parent.
1408
1408
  */
1409
1409
  entity_id?: string | null;
1410
1410
  };
@@ -1786,6 +1786,32 @@ export type ClosePeriodResponse = {
1786
1786
  * 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.
1787
1787
  */
1788
1788
  statements_stamped?: boolean;
1789
+ /**
1790
+ * Shadow
1791
+ *
1792
+ * True when the close ran in shadow (the QuickBooks connection's write_policy is 'shadow'): nothing was written to QuickBooks, nothing posted, the in-window drafts were shadowed, and the gates that would have blocked the close are in gate_findings.
1793
+ */
1794
+ shadow?: boolean;
1795
+ /**
1796
+ * Entries Shadowed
1797
+ *
1798
+ * Drafts a shadow close took as expectations (status 'shadowed') instead of posting. Always 0 outside shadow.
1799
+ */
1800
+ entries_shadowed?: number;
1801
+ /**
1802
+ * Gate Findings
1803
+ *
1804
+ * Blocker codes a shadow close recorded instead of enforcing: sync_stale, pending_obligations, stranded_obligations, reconciling_items, unposted_source_events, unreconciled_accounts. Empty outside shadow.
1805
+ */
1806
+ gate_findings?: Array<string>;
1807
+ /**
1808
+ * Gate Finding Counts
1809
+ *
1810
+ * Each finding's size: days stale for sync_stale, a count for the rest.
1811
+ */
1812
+ gate_finding_counts?: {
1813
+ [key: string]: number;
1814
+ };
1789
1815
  /**
1790
1816
  * Statement Stamp Note
1791
1817
  *
@@ -1939,7 +1965,7 @@ export type ComputeMetricsRequest = {
1939
1965
  /**
1940
1966
  * Entity Id
1941
1967
  *
1942
- * Entity to compute for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
1968
+ * The entity whose metrics to compute, by id. Omit for the group parent.
1943
1969
  */
1944
1970
  entity_id?: string | null;
1945
1971
  /**
@@ -2959,7 +2985,7 @@ export type CreateForecastRequest = {
2959
2985
  /**
2960
2986
  * Entity Id
2961
2987
  *
2962
- * Entity the scenario belongs to. Defaults to the graph's earliest-created entity (single-entity convention).
2988
+ * The entity the scenario belongs to, by id: its history and its computed months are that entity's books. Omit for the group parent.
2963
2989
  */
2964
2990
  entity_id?: string | null;
2965
2991
  };
@@ -3298,6 +3324,12 @@ export type CreateScheduleRequest = {
3298
3324
  * Schedule name
3299
3325
  */
3300
3326
  name: string;
3327
+ /**
3328
+ * Entity Id
3329
+ *
3330
+ * The entity whose books the schedule belongs to, by id. Omit for the group parent. Its facts, obligations and closing entries land in that entity's books, against that entity's own accounts.
3331
+ */
3332
+ entity_id?: string | null;
3301
3333
  /**
3302
3334
  * Taxonomy Id
3303
3335
  *
@@ -7696,6 +7728,12 @@ export type InformationBlockEnvelope = {
7696
7728
  * Qname of the named Disclosure this block corresponds to (e.g., 'disclosures:BalanceSheet'), when an inbound reportedDisclosure-requiresDisclosure arc identifies one. Null for tenant-authored blocks without a Disclosure mapping.
7697
7729
  */
7698
7730
  disclosure_id?: string | null;
7731
+ /**
7732
+ * Entity Id
7733
+ *
7734
+ * The entity whose books the envelope reads. A schedule, reconciliation or forecast is one entity's own and always reads its owner's; a block shared by the group (statements, metrics) reads the entity asked for, else the group parent. Null on the library and on a graph with no entity yet.
7735
+ */
7736
+ entity_id?: string | null;
7699
7737
  information_model: InformationModelResponse;
7700
7738
  artifact: ArtifactResponse;
7701
7739
  /**
@@ -9227,7 +9265,7 @@ export type LinkBankAccountResponse = {
9227
9265
  /**
9228
9266
  * Changed
9229
9267
  *
9230
- * False when the link already stood.
9268
+ * False when the link already stood and no line moved.
9231
9269
  */
9232
9270
  changed?: boolean;
9233
9271
  };
@@ -9690,8 +9728,9 @@ export type MemoryRecord = {
9690
9728
  *
9691
9729
  * Mercury bank-feed connection configuration.
9692
9730
  *
9693
- * A bank feed is native accounting: the graph must already have a chart of
9694
- * accounts and no live QuickBooks connection. Over OAuth (the hosted
9731
+ * A bank feed is native accounting: the entity its accounts land on must
9732
+ * already have a chart of accounts and must not be the one QuickBooks keeps
9733
+ * (the group parent, while QuickBooks is connected). Over OAuth (the hosted
9695
9734
  * default) the connection is created `pending_oauth` and activated by the
9696
9735
  * callback. `api_key` — a personal **read-only** Mercury token — connects
9697
9736
  * at once without a browser round-trip, but only on deployments that turn
@@ -17586,9 +17625,9 @@ export type SetWritePolicyRequest = {
17586
17625
  /**
17587
17626
  * Write Policy
17588
17627
  *
17589
- * 'native' = RoboSystems authoritative, no write-back; 'qb_authoritative' = QuickBooks authoritative, entries publish to QB.
17628
+ * 'qb_authoritative' = QuickBooks authoritative, entries publish to QB; 'shadow' = QuickBooks authoritative and RoboSystems only observes: nothing is written to QuickBooks, the close posts nothing locally, its drafts become shadowed expectations and its gates are findings. 'native', books kept in RoboSystems with no write-back, is what disconnecting or severing leaves, not a choice for a live connection.
17590
17629
  */
17591
- write_policy: 'native' | 'qb_authoritative';
17630
+ write_policy: 'qb_authoritative' | 'shadow';
17592
17631
  };
17593
17632
 
17594
17633
  /**
package/sdk.gen.d.ts CHANGED
@@ -320,7 +320,7 @@ export declare const listConnections: <ThrowOnError extends boolean = false>(opt
320
320
  /**
321
321
  * Create Connection
322
322
  *
323
- * QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — `POST /oauth/init` returns a `link_token` for Plaid Link. A bank feed (Mercury, Plaid) is refused (409) beside a live QuickBooks connection or on a graph with no chart of accounts.
323
+ * QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — `POST /oauth/init` returns a `link_token` for Plaid Link. A bank feed (Mercury, Plaid) names the entity its accounts book to (`entity_id`, the group parent when omitted) and is refused (409) when that entity has no chart of accounts or is the one QuickBooks keeps; QuickBooks is refused (409) when the group parent's books are already native.
324
324
  */
325
325
  export declare const createConnection: <ThrowOnError extends boolean = false>(options: Options<CreateConnectionData, ThrowOnError>) => RequestResult<CreateConnectionResponses, CreateConnectionErrors, ThrowOnError>;
326
326
  /**
@@ -352,7 +352,7 @@ export declare const syncConnection: <ThrowOnError extends boolean = false>(opti
352
352
  /**
353
353
  * Set Connection Write Policy
354
354
  *
355
- * Opt a connection into or out of outbound write-back. 'qb_authoritative' makes QuickBooks the source of truth — RoboSystems-originated entries (manual JEs, schedule drafts) publish to QuickBooks when executed or at close. 'native' keeps RoboSystems authoritative with no write-back. This is the explicit operator opt-in for writing to your books of record.
355
+ * Choose how a live connection and RoboSystems share the books. 'qb_authoritative', the default, makes QuickBooks the book of record: RoboSystems-originated entries (manual JEs, schedule drafts) publish to QuickBooks when executed or at close. 'shadow' keeps QuickBooks the book of record and writes nothing to it: the close posts nothing locally either, its drafts become shadowed expectations compared with what QuickBooks holds, and its gates are recorded as findings. 'native' is not a choice here: it is what disconnecting or severing leaves, books kept in RoboSystems with no connection to write to. This is the explicit operator opt-in for writing to your books of record.
356
356
  */
357
357
  export declare const setConnectionWritePolicy: <ThrowOnError extends boolean = false>(options: Options<SetConnectionWritePolicyData, ThrowOnError>) => RequestResult<SetConnectionWritePolicyResponses, SetConnectionWritePolicyErrors, ThrowOnError>;
358
358
  /**
@@ -1136,7 +1136,7 @@ export declare const setCloseTarget: <ThrowOnError extends boolean = false>(opti
1136
1136
  /**
1137
1137
  * Close Fiscal Period
1138
1138
  *
1139
- * Lock a single fiscal period. Posts draft entries, runs the balance-sheet equation check, advances `closed_through` by one, auto-advances `close_target` if this close caught up to it, and stamps the period's canonical statement FactSets from the posted ledger (`statements_stamped` / `stamped_statement_sets` in the response; soft-skipped with `statement_stamp_note` when reporting isn't set up). Period must be exactly `closed_through + 1` — sequence violations return 422 with structured `blockers`. Common blockers: `sync_stale` (override with `allow_stale_sync=true` after manual verification), `period_incomplete` (draft entries unbalanced), `sequence_violation` (out-of-order).
1139
+ * Lock a single fiscal period. Posts draft entries, runs the balance-sheet equation check, advances `closed_through` by one, auto-advances `close_target` if this close caught up to it, and stamps the period's canonical statement FactSets from the posted ledger (`statements_stamped` / `stamped_statement_sets` in the response; soft-skipped with `statement_stamp_note` when reporting isn't set up). Period must be exactly `closed_through + 1` — sequence violations return 422 with structured `blockers`. Common blockers: `sync_stale` (override with `allow_stale_sync=true` after manual verification), `period_incomplete` (draft entries unbalanced), `sequence_violation` (out-of-order). Under a QuickBooks connection whose write_policy is `shadow`, the close observes instead: nothing is written to QuickBooks or posted, the drafts become `shadowed` expectations (`entries_shadowed`), and the gates that would have blocked are returned as `gate_findings` rather than enforced.
1140
1140
  *
1141
1141
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
1142
1142
  */
package/sdk.gen.js CHANGED
@@ -614,7 +614,7 @@ exports.listConnections = listConnections;
614
614
  /**
615
615
  * Create Connection
616
616
  *
617
- * QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — `POST /oauth/init` returns a `link_token` for Plaid Link. A bank feed (Mercury, Plaid) is refused (409) beside a live QuickBooks connection or on a graph with no chart of accounts.
617
+ * QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — `POST /oauth/init` returns a `link_token` for Plaid Link. A bank feed (Mercury, Plaid) names the entity its accounts book to (`entity_id`, the group parent when omitted) and is refused (409) when that entity has no chart of accounts or is the one QuickBooks keeps; QuickBooks is refused (409) when the group parent's books are already native.
618
618
  */
619
619
  const createConnection = (options) => (options.client ?? client_gen_1.client).post({
620
620
  security: [{ name: 'X-API-Key', type: 'apiKey' }, { scheme: 'bearer', type: 'http' }],
@@ -692,7 +692,7 @@ exports.syncConnection = syncConnection;
692
692
  /**
693
693
  * Set Connection Write Policy
694
694
  *
695
- * Opt a connection into or out of outbound write-back. 'qb_authoritative' makes QuickBooks the source of truth — RoboSystems-originated entries (manual JEs, schedule drafts) publish to QuickBooks when executed or at close. 'native' keeps RoboSystems authoritative with no write-back. This is the explicit operator opt-in for writing to your books of record.
695
+ * Choose how a live connection and RoboSystems share the books. 'qb_authoritative', the default, makes QuickBooks the book of record: RoboSystems-originated entries (manual JEs, schedule drafts) publish to QuickBooks when executed or at close. 'shadow' keeps QuickBooks the book of record and writes nothing to it: the close posts nothing locally either, its drafts become shadowed expectations compared with what QuickBooks holds, and its gates are recorded as findings. 'native' is not a choice here: it is what disconnecting or severing leaves, books kept in RoboSystems with no connection to write to. This is the explicit operator opt-in for writing to your books of record.
696
696
  */
697
697
  const setConnectionWritePolicy = (options) => (options.client ?? client_gen_1.client).put({
698
698
  security: [{ name: 'X-API-Key', type: 'apiKey' }, { scheme: 'bearer', type: 'http' }],
@@ -2340,7 +2340,7 @@ exports.setCloseTarget = setCloseTarget;
2340
2340
  /**
2341
2341
  * Close Fiscal Period
2342
2342
  *
2343
- * Lock a single fiscal period. Posts draft entries, runs the balance-sheet equation check, advances `closed_through` by one, auto-advances `close_target` if this close caught up to it, and stamps the period's canonical statement FactSets from the posted ledger (`statements_stamped` / `stamped_statement_sets` in the response; soft-skipped with `statement_stamp_note` when reporting isn't set up). Period must be exactly `closed_through + 1` — sequence violations return 422 with structured `blockers`. Common blockers: `sync_stale` (override with `allow_stale_sync=true` after manual verification), `period_incomplete` (draft entries unbalanced), `sequence_violation` (out-of-order).
2343
+ * Lock a single fiscal period. Posts draft entries, runs the balance-sheet equation check, advances `closed_through` by one, auto-advances `close_target` if this close caught up to it, and stamps the period's canonical statement FactSets from the posted ledger (`statements_stamped` / `stamped_statement_sets` in the response; soft-skipped with `statement_stamp_note` when reporting isn't set up). Period must be exactly `closed_through + 1` — sequence violations return 422 with structured `blockers`. Common blockers: `sync_stale` (override with `allow_stale_sync=true` after manual verification), `period_incomplete` (draft entries unbalanced), `sequence_violation` (out-of-order). Under a QuickBooks connection whose write_policy is `shadow`, the close observes instead: nothing is written to QuickBooks or posted, the drafts become `shadowed` expectations (`entries_shadowed`), and the gates that would have blocked are returned as `gate_findings` rather than enforced.
2344
2344
  *
2345
2345
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
2346
2346
  */
package/sdk.gen.ts CHANGED
@@ -625,7 +625,7 @@ export const listConnections = <ThrowOnError extends boolean = false>(options: O
625
625
  /**
626
626
  * Create Connection
627
627
  *
628
- * QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — `POST /oauth/init` returns a `link_token` for Plaid Link. A bank feed (Mercury, Plaid) is refused (409) beside a live QuickBooks connection or on a graph with no chart of accounts.
628
+ * QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — `POST /oauth/init` returns a `link_token` for Plaid Link. A bank feed (Mercury, Plaid) names the entity its accounts book to (`entity_id`, the group parent when omitted) and is refused (409) when that entity has no chart of accounts or is the one QuickBooks keeps; QuickBooks is refused (409) when the group parent's books are already native.
629
629
  */
630
630
  export const createConnection = <ThrowOnError extends boolean = false>(options: Options<CreateConnectionData, ThrowOnError>): RequestResult<CreateConnectionResponses, CreateConnectionErrors, ThrowOnError> => (options.client ?? client).post<CreateConnectionResponses, CreateConnectionErrors, ThrowOnError>({
631
631
  security: [{ name: 'X-API-Key', type: 'apiKey' }, { scheme: 'bearer', type: 'http' }],
@@ -703,7 +703,7 @@ export const syncConnection = <ThrowOnError extends boolean = false>(options: Op
703
703
  /**
704
704
  * Set Connection Write Policy
705
705
  *
706
- * Opt a connection into or out of outbound write-back. 'qb_authoritative' makes QuickBooks the source of truth — RoboSystems-originated entries (manual JEs, schedule drafts) publish to QuickBooks when executed or at close. 'native' keeps RoboSystems authoritative with no write-back. This is the explicit operator opt-in for writing to your books of record.
706
+ * Choose how a live connection and RoboSystems share the books. 'qb_authoritative', the default, makes QuickBooks the book of record: RoboSystems-originated entries (manual JEs, schedule drafts) publish to QuickBooks when executed or at close. 'shadow' keeps QuickBooks the book of record and writes nothing to it: the close posts nothing locally either, its drafts become shadowed expectations compared with what QuickBooks holds, and its gates are recorded as findings. 'native' is not a choice here: it is what disconnecting or severing leaves, books kept in RoboSystems with no connection to write to. This is the explicit operator opt-in for writing to your books of record.
707
707
  */
708
708
  export const setConnectionWritePolicy = <ThrowOnError extends boolean = false>(options: Options<SetConnectionWritePolicyData, ThrowOnError>): RequestResult<SetConnectionWritePolicyResponses, SetConnectionWritePolicyErrors, ThrowOnError> => (options.client ?? client).put<SetConnectionWritePolicyResponses, SetConnectionWritePolicyErrors, ThrowOnError>({
709
709
  security: [{ name: 'X-API-Key', type: 'apiKey' }, { scheme: 'bearer', type: 'http' }],
@@ -2351,7 +2351,7 @@ export const setCloseTarget = <ThrowOnError extends boolean = false>(options: Op
2351
2351
  /**
2352
2352
  * Close Fiscal Period
2353
2353
  *
2354
- * Lock a single fiscal period. Posts draft entries, runs the balance-sheet equation check, advances `closed_through` by one, auto-advances `close_target` if this close caught up to it, and stamps the period's canonical statement FactSets from the posted ledger (`statements_stamped` / `stamped_statement_sets` in the response; soft-skipped with `statement_stamp_note` when reporting isn't set up). Period must be exactly `closed_through + 1` — sequence violations return 422 with structured `blockers`. Common blockers: `sync_stale` (override with `allow_stale_sync=true` after manual verification), `period_incomplete` (draft entries unbalanced), `sequence_violation` (out-of-order).
2354
+ * Lock a single fiscal period. Posts draft entries, runs the balance-sheet equation check, advances `closed_through` by one, auto-advances `close_target` if this close caught up to it, and stamps the period's canonical statement FactSets from the posted ledger (`statements_stamped` / `stamped_statement_sets` in the response; soft-skipped with `statement_stamp_note` when reporting isn't set up). Period must be exactly `closed_through + 1` — sequence violations return 422 with structured `blockers`. Common blockers: `sync_stale` (override with `allow_stale_sync=true` after manual verification), `period_incomplete` (draft entries unbalanced), `sequence_violation` (out-of-order). Under a QuickBooks connection whose write_policy is `shadow`, the close observes instead: nothing is written to QuickBooks or posted, the drafts become `shadowed` expectations (`entries_shadowed`), and the gates that would have blocked are returned as `gate_findings` rather than enforced.
2355
2355
  *
2356
2356
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
2357
2357
  */
package/types.gen.d.ts CHANGED
@@ -263,7 +263,7 @@ export type AssertMetricsRequest = {
263
263
  /**
264
264
  * Entity Id
265
265
  *
266
- * Entity to assert for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
266
+ * The entity the asserted values belong to, by id. Omit for the group parent.
267
267
  */
268
268
  entity_id?: string | null;
269
269
  /**
@@ -1141,7 +1141,7 @@ export type BindTextBlockRequest = {
1141
1141
  /**
1142
1142
  * Entity Id
1143
1143
  *
1144
- * Entity the fact belongs to; defaults to the primary entity.
1144
+ * Entity the fact belongs to, by id; omit for the group parent.
1145
1145
  */
1146
1146
  entity_id?: string | null;
1147
1147
  };
@@ -1366,7 +1366,7 @@ export type ChangeReportingStyleRequest = {
1366
1366
  /**
1367
1367
  * Entity Id
1368
1368
  *
1369
- * Target entity. Omit to target the graph's primary (earliest-created) entity — the single-entity default.
1369
+ * The entity whose style to change, by id. Omit for the group parent.
1370
1370
  */
1371
1371
  entity_id?: string | null;
1372
1372
  };
@@ -1738,6 +1738,32 @@ export type ClosePeriodResponse = {
1738
1738
  * 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.
1739
1739
  */
1740
1740
  statements_stamped?: boolean;
1741
+ /**
1742
+ * Shadow
1743
+ *
1744
+ * True when the close ran in shadow (the QuickBooks connection's write_policy is 'shadow'): nothing was written to QuickBooks, nothing posted, the in-window drafts were shadowed, and the gates that would have blocked the close are in gate_findings.
1745
+ */
1746
+ shadow?: boolean;
1747
+ /**
1748
+ * Entries Shadowed
1749
+ *
1750
+ * Drafts a shadow close took as expectations (status 'shadowed') instead of posting. Always 0 outside shadow.
1751
+ */
1752
+ entries_shadowed?: number;
1753
+ /**
1754
+ * Gate Findings
1755
+ *
1756
+ * Blocker codes a shadow close recorded instead of enforcing: sync_stale, pending_obligations, stranded_obligations, reconciling_items, unposted_source_events, unreconciled_accounts. Empty outside shadow.
1757
+ */
1758
+ gate_findings?: Array<string>;
1759
+ /**
1760
+ * Gate Finding Counts
1761
+ *
1762
+ * Each finding's size: days stale for sync_stale, a count for the rest.
1763
+ */
1764
+ gate_finding_counts?: {
1765
+ [key: string]: number;
1766
+ };
1741
1767
  /**
1742
1768
  * Statement Stamp Note
1743
1769
  *
@@ -1888,7 +1914,7 @@ export type ComputeMetricsRequest = {
1888
1914
  /**
1889
1915
  * Entity Id
1890
1916
  *
1891
- * Entity to compute for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
1917
+ * The entity whose metrics to compute, by id. Omit for the group parent.
1892
1918
  */
1893
1919
  entity_id?: string | null;
1894
1920
  /**
@@ -2891,7 +2917,7 @@ export type CreateForecastRequest = {
2891
2917
  /**
2892
2918
  * Entity Id
2893
2919
  *
2894
- * Entity the scenario belongs to. Defaults to the graph's earliest-created entity (single-entity convention).
2920
+ * The entity the scenario belongs to, by id: its history and its computed months are that entity's books. Omit for the group parent.
2895
2921
  */
2896
2922
  entity_id?: string | null;
2897
2923
  };
@@ -3220,6 +3246,12 @@ export type CreateScheduleRequest = {
3220
3246
  * Schedule name
3221
3247
  */
3222
3248
  name: string;
3249
+ /**
3250
+ * Entity Id
3251
+ *
3252
+ * The entity whose books the schedule belongs to, by id. Omit for the group parent. Its facts, obligations and closing entries land in that entity's books, against that entity's own accounts.
3253
+ */
3254
+ entity_id?: string | null;
3223
3255
  /**
3224
3256
  * Taxonomy Id
3225
3257
  *
@@ -7518,6 +7550,12 @@ export type InformationBlockEnvelope = {
7518
7550
  * Qname of the named Disclosure this block corresponds to (e.g., 'disclosures:BalanceSheet'), when an inbound reportedDisclosure-requiresDisclosure arc identifies one. Null for tenant-authored blocks without a Disclosure mapping.
7519
7551
  */
7520
7552
  disclosure_id?: string | null;
7553
+ /**
7554
+ * Entity Id
7555
+ *
7556
+ * The entity whose books the envelope reads. A schedule, reconciliation or forecast is one entity's own and always reads its owner's; a block shared by the group (statements, metrics) reads the entity asked for, else the group parent. Null on the library and on a graph with no entity yet.
7557
+ */
7558
+ entity_id?: string | null;
7521
7559
  information_model: InformationModelResponse;
7522
7560
  artifact: ArtifactResponse;
7523
7561
  /**
@@ -9021,7 +9059,7 @@ export type LinkBankAccountResponse = {
9021
9059
  /**
9022
9060
  * Changed
9023
9061
  *
9024
- * False when the link already stood.
9062
+ * False when the link already stood and no line moved.
9025
9063
  */
9026
9064
  changed?: boolean;
9027
9065
  };
@@ -9472,8 +9510,9 @@ export type MemoryRecord = {
9472
9510
  *
9473
9511
  * Mercury bank-feed connection configuration.
9474
9512
  *
9475
- * A bank feed is native accounting: the graph must already have a chart of
9476
- * accounts and no live QuickBooks connection. Over OAuth (the hosted
9513
+ * A bank feed is native accounting: the entity its accounts land on must
9514
+ * already have a chart of accounts and must not be the one QuickBooks keeps
9515
+ * (the group parent, while QuickBooks is connected). Over OAuth (the hosted
9477
9516
  * default) the connection is created `pending_oauth` and activated by the
9478
9517
  * callback. `api_key` — a personal **read-only** Mercury token — connects
9479
9518
  * at once without a browser round-trip, but only on deployments that turn
@@ -17177,9 +17216,9 @@ export type SetWritePolicyRequest = {
17177
17216
  /**
17178
17217
  * Write Policy
17179
17218
  *
17180
- * 'native' = RoboSystems authoritative, no write-back; 'qb_authoritative' = QuickBooks authoritative, entries publish to QB.
17219
+ * 'qb_authoritative' = QuickBooks authoritative, entries publish to QB; 'shadow' = QuickBooks authoritative and RoboSystems only observes: nothing is written to QuickBooks, the close posts nothing locally, its drafts become shadowed expectations and its gates are findings. 'native', books kept in RoboSystems with no write-back, is what disconnecting or severing leaves, not a choice for a live connection.
17181
17220
  */
17182
- write_policy: 'native' | 'qb_authoritative';
17221
+ write_policy: 'qb_authoritative' | 'shadow';
17183
17222
  };
17184
17223
  /**
17185
17224
  * ShareReportOperation
package/types.gen.ts CHANGED
@@ -273,7 +273,7 @@ export type AssertMetricsRequest = {
273
273
  /**
274
274
  * Entity Id
275
275
  *
276
- * Entity to assert for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
276
+ * The entity the asserted values belong to, by id. Omit for the group parent.
277
277
  */
278
278
  entity_id?: string | null;
279
279
  /**
@@ -1172,7 +1172,7 @@ export type BindTextBlockRequest = {
1172
1172
  /**
1173
1173
  * Entity Id
1174
1174
  *
1175
- * Entity the fact belongs to; defaults to the primary entity.
1175
+ * Entity the fact belongs to, by id; omit for the group parent.
1176
1176
  */
1177
1177
  entity_id?: string | null;
1178
1178
  };
@@ -1404,7 +1404,7 @@ export type ChangeReportingStyleRequest = {
1404
1404
  /**
1405
1405
  * Entity Id
1406
1406
  *
1407
- * Target entity. Omit to target the graph's primary (earliest-created) entity — the single-entity default.
1407
+ * The entity whose style to change, by id. Omit for the group parent.
1408
1408
  */
1409
1409
  entity_id?: string | null;
1410
1410
  };
@@ -1786,6 +1786,32 @@ export type ClosePeriodResponse = {
1786
1786
  * 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.
1787
1787
  */
1788
1788
  statements_stamped?: boolean;
1789
+ /**
1790
+ * Shadow
1791
+ *
1792
+ * True when the close ran in shadow (the QuickBooks connection's write_policy is 'shadow'): nothing was written to QuickBooks, nothing posted, the in-window drafts were shadowed, and the gates that would have blocked the close are in gate_findings.
1793
+ */
1794
+ shadow?: boolean;
1795
+ /**
1796
+ * Entries Shadowed
1797
+ *
1798
+ * Drafts a shadow close took as expectations (status 'shadowed') instead of posting. Always 0 outside shadow.
1799
+ */
1800
+ entries_shadowed?: number;
1801
+ /**
1802
+ * Gate Findings
1803
+ *
1804
+ * Blocker codes a shadow close recorded instead of enforcing: sync_stale, pending_obligations, stranded_obligations, reconciling_items, unposted_source_events, unreconciled_accounts. Empty outside shadow.
1805
+ */
1806
+ gate_findings?: Array<string>;
1807
+ /**
1808
+ * Gate Finding Counts
1809
+ *
1810
+ * Each finding's size: days stale for sync_stale, a count for the rest.
1811
+ */
1812
+ gate_finding_counts?: {
1813
+ [key: string]: number;
1814
+ };
1789
1815
  /**
1790
1816
  * Statement Stamp Note
1791
1817
  *
@@ -1939,7 +1965,7 @@ export type ComputeMetricsRequest = {
1939
1965
  /**
1940
1966
  * Entity Id
1941
1967
  *
1942
- * Entity to compute for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
1968
+ * The entity whose metrics to compute, by id. Omit for the group parent.
1943
1969
  */
1944
1970
  entity_id?: string | null;
1945
1971
  /**
@@ -2959,7 +2985,7 @@ export type CreateForecastRequest = {
2959
2985
  /**
2960
2986
  * Entity Id
2961
2987
  *
2962
- * Entity the scenario belongs to. Defaults to the graph's earliest-created entity (single-entity convention).
2988
+ * The entity the scenario belongs to, by id: its history and its computed months are that entity's books. Omit for the group parent.
2963
2989
  */
2964
2990
  entity_id?: string | null;
2965
2991
  };
@@ -3298,6 +3324,12 @@ export type CreateScheduleRequest = {
3298
3324
  * Schedule name
3299
3325
  */
3300
3326
  name: string;
3327
+ /**
3328
+ * Entity Id
3329
+ *
3330
+ * The entity whose books the schedule belongs to, by id. Omit for the group parent. Its facts, obligations and closing entries land in that entity's books, against that entity's own accounts.
3331
+ */
3332
+ entity_id?: string | null;
3301
3333
  /**
3302
3334
  * Taxonomy Id
3303
3335
  *
@@ -7696,6 +7728,12 @@ export type InformationBlockEnvelope = {
7696
7728
  * Qname of the named Disclosure this block corresponds to (e.g., 'disclosures:BalanceSheet'), when an inbound reportedDisclosure-requiresDisclosure arc identifies one. Null for tenant-authored blocks without a Disclosure mapping.
7697
7729
  */
7698
7730
  disclosure_id?: string | null;
7731
+ /**
7732
+ * Entity Id
7733
+ *
7734
+ * The entity whose books the envelope reads. A schedule, reconciliation or forecast is one entity's own and always reads its owner's; a block shared by the group (statements, metrics) reads the entity asked for, else the group parent. Null on the library and on a graph with no entity yet.
7735
+ */
7736
+ entity_id?: string | null;
7699
7737
  information_model: InformationModelResponse;
7700
7738
  artifact: ArtifactResponse;
7701
7739
  /**
@@ -9227,7 +9265,7 @@ export type LinkBankAccountResponse = {
9227
9265
  /**
9228
9266
  * Changed
9229
9267
  *
9230
- * False when the link already stood.
9268
+ * False when the link already stood and no line moved.
9231
9269
  */
9232
9270
  changed?: boolean;
9233
9271
  };
@@ -9690,8 +9728,9 @@ export type MemoryRecord = {
9690
9728
  *
9691
9729
  * Mercury bank-feed connection configuration.
9692
9730
  *
9693
- * A bank feed is native accounting: the graph must already have a chart of
9694
- * accounts and no live QuickBooks connection. Over OAuth (the hosted
9731
+ * A bank feed is native accounting: the entity its accounts land on must
9732
+ * already have a chart of accounts and must not be the one QuickBooks keeps
9733
+ * (the group parent, while QuickBooks is connected). Over OAuth (the hosted
9695
9734
  * default) the connection is created `pending_oauth` and activated by the
9696
9735
  * callback. `api_key` — a personal **read-only** Mercury token — connects
9697
9736
  * at once without a browser round-trip, but only on deployments that turn
@@ -17586,9 +17625,9 @@ export type SetWritePolicyRequest = {
17586
17625
  /**
17587
17626
  * Write Policy
17588
17627
  *
17589
- * 'native' = RoboSystems authoritative, no write-back; 'qb_authoritative' = QuickBooks authoritative, entries publish to QB.
17628
+ * 'qb_authoritative' = QuickBooks authoritative, entries publish to QB; 'shadow' = QuickBooks authoritative and RoboSystems only observes: nothing is written to QuickBooks, the close posts nothing locally, its drafts become shadowed expectations and its gates are findings. 'native', books kept in RoboSystems with no write-back, is what disconnecting or severing leaves, not a choice for a live connection.
17590
17629
  */
17591
- write_policy: 'native' | 'qb_authoritative';
17630
+ write_policy: 'qb_authoritative' | 'shadow';
17592
17631
  };
17593
17632
 
17594
17633
  /**