@lightsparkdev/lightspark-sdk 1.2.2 → 1.2.3

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.
Files changed (117) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/dist/{BitcoinNetwork-a816c0be.d.ts → BitcoinNetwork-37e9f091.d.ts} +8 -3
  3. package/dist/env.d.cts +1 -1
  4. package/dist/env.d.ts +1 -1
  5. package/dist/{index-eb604025.d.ts → index-449c9f58.d.ts} +1461 -675
  6. package/dist/index.cjs +341 -307
  7. package/dist/index.d.cts +3 -3
  8. package/dist/index.d.ts +3 -3
  9. package/dist/index.js +323 -289
  10. package/dist/objects/index.d.cts +2 -2
  11. package/dist/objects/index.d.ts +2 -2
  12. package/dist/objects/index.js +1 -1
  13. package/package.json +4 -4
  14. package/src/NodeKeyLoaderCache.ts +4 -3
  15. package/src/SigningKeyLoader.ts +12 -7
  16. package/src/client.ts +99 -65
  17. package/src/env.ts +3 -1
  18. package/src/objects/Account.ts +7 -3
  19. package/src/objects/AccountToApiTokensConnection.ts +7 -3
  20. package/src/objects/AccountToChannelsConnection.ts +3 -2
  21. package/src/objects/AccountToNodesConnection.ts +7 -3
  22. package/src/objects/AccountToPaymentRequestsConnection.ts +7 -3
  23. package/src/objects/AccountToTransactionsConnection.ts +13 -9
  24. package/src/objects/AccountToWalletsConnection.ts +7 -3
  25. package/src/objects/ApiToken.ts +13 -7
  26. package/src/objects/Balances.ts +22 -12
  27. package/src/objects/BitcoinNetwork.ts +8 -3
  28. package/src/objects/BlockchainBalance.ts +4 -1
  29. package/src/objects/Channel.ts +37 -14
  30. package/src/objects/ChannelClosingTransaction.ts +22 -11
  31. package/src/objects/ChannelFees.ts +4 -1
  32. package/src/objects/ChannelOpeningTransaction.ts +22 -11
  33. package/src/objects/ChannelStatus.ts +33 -8
  34. package/src/objects/ChannelToTransactionsConnection.ts +9 -8
  35. package/src/objects/ComplianceProvider.ts +3 -2
  36. package/src/objects/Connection.ts +7 -3
  37. package/src/objects/CreateApiTokenInput.ts +4 -1
  38. package/src/objects/CreateApiTokenOutput.ts +3 -3
  39. package/src/objects/CreateLnurlInvoiceInput.ts +3 -2
  40. package/src/objects/CreateTestModePaymentInput.ts +2 -2
  41. package/src/objects/CreateTestModePaymentoutput.ts +5 -1
  42. package/src/objects/CurrencyAmount.ts +6 -4
  43. package/src/objects/CurrencyUnit.ts +36 -9
  44. package/src/objects/Deposit.ts +22 -11
  45. package/src/objects/Entity.ts +8 -3
  46. package/src/objects/FeeEstimate.ts +5 -1
  47. package/src/objects/GraphNode.ts +30 -14
  48. package/src/objects/Hop.ts +12 -4
  49. package/src/objects/HtlcAttemptFailureCode.ts +7 -3
  50. package/src/objects/IncentivesIneligibilityReason.ts +33 -9
  51. package/src/objects/IncentivesStatus.ts +14 -4
  52. package/src/objects/IncomingPayment.ts +18 -7
  53. package/src/objects/IncomingPaymentAttempt.ts +8 -3
  54. package/src/objects/IncomingPaymentAttemptStatus.ts +7 -3
  55. package/src/objects/IncomingPaymentToAttemptsConnection.ts +7 -3
  56. package/src/objects/Invoice.ts +2 -2
  57. package/src/objects/InvoiceData.ts +7 -3
  58. package/src/objects/InvoiceType.ts +3 -2
  59. package/src/objects/LightningFeeEstimateForInvoiceInput.ts +2 -2
  60. package/src/objects/LightningTransaction.ts +12 -4
  61. package/src/objects/LightsparkNode.ts +33 -18
  62. package/src/objects/LightsparkNodeOwner.ts +2 -2
  63. package/src/objects/LightsparkNodeStatus.ts +3 -2
  64. package/src/objects/LightsparkNodeToChannelsConnection.ts +7 -3
  65. package/src/objects/LightsparkNodeWithOSK.ts +35 -19
  66. package/src/objects/LightsparkNodeWithRemoteSigning.ts +31 -18
  67. package/src/objects/Node.ts +28 -14
  68. package/src/objects/NodeAddressType.ts +7 -3
  69. package/src/objects/NodeToAddressesConnection.ts +7 -3
  70. package/src/objects/OnChainTransaction.ts +23 -11
  71. package/src/objects/OutgoingPayment.ts +24 -7
  72. package/src/objects/OutgoingPaymentAttempt.ts +28 -13
  73. package/src/objects/OutgoingPaymentAttemptStatus.ts +7 -3
  74. package/src/objects/OutgoingPaymentAttemptToHopsConnection.ts +12 -4
  75. package/src/objects/OutgoingPaymentToAttemptsConnection.ts +7 -3
  76. package/src/objects/PageInfo.ts +6 -1
  77. package/src/objects/PayInvoiceInput.ts +6 -3
  78. package/src/objects/PaymentDirection.ts +3 -2
  79. package/src/objects/PaymentFailureReason.ts +7 -3
  80. package/src/objects/PaymentRequest.ts +8 -3
  81. package/src/objects/PaymentRequestData.ts +5 -1
  82. package/src/objects/PaymentRequestStatus.ts +7 -3
  83. package/src/objects/Permission.ts +7 -3
  84. package/src/objects/PostTransactionData.ts +6 -3
  85. package/src/objects/RegionCode.ts +43 -12
  86. package/src/objects/RegisterPaymentInput.ts +12 -7
  87. package/src/objects/RemoteSigningSubEventType.ts +7 -3
  88. package/src/objects/RequestWithdrawalInput.ts +2 -2
  89. package/src/objects/RiskRating.ts +8 -3
  90. package/src/objects/RoutingTransaction.ts +20 -7
  91. package/src/objects/RoutingTransactionFailureReason.ts +8 -3
  92. package/src/objects/ScreenNodeInput.ts +3 -2
  93. package/src/objects/SendPaymentInput.ts +4 -1
  94. package/src/objects/SetInvoicePaymentHashInput.ts +3 -2
  95. package/src/objects/Signable.ts +2 -2
  96. package/src/objects/SignablePayload.ts +6 -3
  97. package/src/objects/SignablePayloadStatus.ts +3 -2
  98. package/src/objects/Transaction.ts +14 -4
  99. package/src/objects/TransactionFailures.ts +4 -1
  100. package/src/objects/TransactionStatus.ts +16 -5
  101. package/src/objects/TransactionType.ts +30 -8
  102. package/src/objects/TransactionUpdate.ts +6 -3
  103. package/src/objects/UmaInvitation.ts +10 -4
  104. package/src/objects/Wallet.ts +13 -4
  105. package/src/objects/WalletStatus.ts +36 -9
  106. package/src/objects/WalletToPaymentRequestsConnection.ts +7 -3
  107. package/src/objects/WalletToTransactionsConnection.ts +7 -3
  108. package/src/objects/WebhookEventType.ts +7 -3
  109. package/src/objects/Withdrawal.ts +22 -11
  110. package/src/objects/WithdrawalMode.ts +7 -3
  111. package/src/objects/WithdrawalRequest.ts +15 -6
  112. package/src/objects/WithdrawalRequestStatus.ts +3 -2
  113. package/src/objects/WithdrawalRequestToChannelClosingTransactionsConnection.ts +11 -4
  114. package/src/objects/WithdrawalRequestToChannelOpeningTransactionsConnection.ts +11 -4
  115. package/src/objects/index.ts +6 -6
  116. package/src/tests/integration/general-regtest.test.ts +1 -1
  117. /package/dist/{chunk-GLL4KTUT.js → chunk-NCPWHRFO.js} +0 -0
package/dist/index.js CHANGED
@@ -86,7 +86,7 @@ import {
86
86
  getTransactionQuery,
87
87
  getUmaInvitationQuery,
88
88
  getWithdrawalQuery
89
- } from "./chunk-GLL4KTUT.js";
89
+ } from "./chunk-NCPWHRFO.js";
90
90
  import {
91
91
  BitcoinNetwork_default
92
92
  } from "./chunk-K6SAUSAX.js";
@@ -129,22 +129,22 @@ var AccountTokenAuthProvider_default = AccountTokenAuthProvider;
129
129
  // src/client.ts
130
130
  import autoBind2 from "auto-bind";
131
131
  import {
132
- createSha256Hash,
133
132
  DefaultCrypto as DefaultCrypto2,
134
133
  LightsparkAuthException,
135
134
  LightsparkException,
136
135
  LightsparkSigningException as LightsparkSigningException3,
137
136
  NodeKeyCache,
138
- pollUntil,
139
137
  Requester,
140
138
  SigningKeyType as SigningKeyType2,
141
- StubAuthProvider
139
+ StubAuthProvider,
140
+ createSha256Hash,
141
+ pollUntil
142
142
  } from "@lightsparkdev/core";
143
143
 
144
144
  // package.json
145
145
  var package_default = {
146
146
  name: "@lightsparkdev/lightspark-sdk",
147
- version: "1.2.2",
147
+ version: "1.2.3",
148
148
  description: "Lightspark JS SDK",
149
149
  author: "Lightspark Inc.",
150
150
  keywords: [
@@ -213,7 +213,7 @@ var package_default = {
213
213
  ],
214
214
  scripts: {
215
215
  build: "yarn tsc && tsup",
216
- "build:watch": "yarn build --watch",
216
+ "build:watch": "yarn build --watch --clean=false",
217
217
  clean: "rm -rf .turbo && rm -rf dist",
218
218
  dev: "yarn build -- --watch",
219
219
  docs: "typedoc src",
@@ -232,7 +232,7 @@ var package_default = {
232
232
  },
233
233
  license: "Apache-2.0",
234
234
  dependencies: {
235
- "@lightsparkdev/core": "1.0.10",
235
+ "@lightsparkdev/core": "1.0.11",
236
236
  "@lightsparkdev/crypto-wasm": "0.1.2",
237
237
  "auto-bind": "^5.0.1",
238
238
  "crypto-browserify": "^3.12.0",
@@ -259,7 +259,192 @@ var package_default = {
259
259
  "tsc-absolute": "^1.0.1",
260
260
  tsup: "^7.2.0",
261
261
  typedoc: "^0.24.7",
262
- typescript: "^4.9.5"
262
+ typescript: "^5.0.0"
263
+ }
264
+ };
265
+
266
+ // src/NodeKeyLoaderCache.ts
267
+ import {
268
+ DefaultCrypto,
269
+ LightsparkSigningException as LightsparkSigningException2
270
+ } from "@lightsparkdev/core";
271
+
272
+ // src/SigningKeyLoader.ts
273
+ import {
274
+ LightsparkSigningException,
275
+ SigningKeyType,
276
+ b64encode as b64encode2,
277
+ isBrowser
278
+ } from "@lightsparkdev/core";
279
+
280
+ // src/graphql/RecoverNodeSigningKey.ts
281
+ var RecoverNodeSigningKey = `
282
+ query RecoverNodeSigningKey($nodeId: ID!) {
283
+ entity(id: $nodeId) {
284
+ __typename
285
+ ... on LightsparkNodeWithOSK {
286
+ encrypted_signing_private_key {
287
+ encrypted_value
288
+ cipher
289
+ }
290
+ }
291
+ }
292
+ }
293
+ `;
294
+
295
+ // src/SigningKeyLoader.ts
296
+ var SIGNING_KEY_PATH = "m/5";
297
+ function isNodeIdAndPasswordSigningKeyLoaderArgs(args) {
298
+ return args.password !== void 0;
299
+ }
300
+ function isMasterSeedSigningKeyLoaderArgs(args) {
301
+ return args.masterSeed !== void 0;
302
+ }
303
+ var NodeIdAndPasswordSigningKeyLoader = class {
304
+ nodeId;
305
+ password;
306
+ requester;
307
+ cryptoImpl;
308
+ constructor(args, requester, cryptoImpl) {
309
+ this.nodeId = args.nodeId;
310
+ this.password = args.password;
311
+ this.requester = requester;
312
+ this.cryptoImpl = cryptoImpl;
313
+ }
314
+ async loadSigningKey() {
315
+ const encryptedKey = await this.recoverNodeSigningKey();
316
+ if (!encryptedKey) {
317
+ console.warn("No encrypted key found for node " + this.nodeId);
318
+ return;
319
+ }
320
+ const signingPrivateKey = await this.cryptoImpl.decryptSecretWithNodePassword(
321
+ encryptedKey.cipher,
322
+ encryptedKey.encrypted_value,
323
+ this.password
324
+ );
325
+ if (!signingPrivateKey) {
326
+ throw new LightsparkSigningException(
327
+ "Unable to decrypt signing key with provided password. Please try again."
328
+ );
329
+ }
330
+ let signingPrivateKeyPEM = "";
331
+ if (new Uint8Array(signingPrivateKey)[0] === 48) {
332
+ signingPrivateKeyPEM = b64encode2(signingPrivateKey);
333
+ } else {
334
+ const dec = new TextDecoder();
335
+ signingPrivateKeyPEM = dec.decode(signingPrivateKey);
336
+ }
337
+ return { key: signingPrivateKeyPEM, type: SigningKeyType.RSASigningKey };
338
+ }
339
+ async recoverNodeSigningKey() {
340
+ const response = await this.requester.makeRawRequest(
341
+ RecoverNodeSigningKey,
342
+ { nodeId: this.nodeId }
343
+ );
344
+ const nodeEntity = response.entity;
345
+ if (nodeEntity?.__typename === "LightsparkNodeWithOSK") {
346
+ return nodeEntity.encrypted_signing_private_key;
347
+ }
348
+ return null;
349
+ }
350
+ };
351
+ var MasterSeedSigningKeyLoader = class {
352
+ masterSeed;
353
+ network;
354
+ constructor(args) {
355
+ this.masterSeed = args.masterSeed;
356
+ this.network = args.network;
357
+ }
358
+ async loadSigningKey() {
359
+ if (isBrowser) {
360
+ throw new LightsparkSigningException(
361
+ "Browser environments not supported for master seed signing key loader."
362
+ );
363
+ }
364
+ const { LightsparkSigner, Network } = await import("@lightsparkdev/crypto-wasm");
365
+ let cryptoLibNetwork;
366
+ switch (this.network) {
367
+ case BitcoinNetwork_default.MAINNET:
368
+ cryptoLibNetwork = Network.Bitcoin;
369
+ break;
370
+ case BitcoinNetwork_default.TESTNET:
371
+ cryptoLibNetwork = Network.Testnet;
372
+ break;
373
+ case BitcoinNetwork_default.REGTEST:
374
+ cryptoLibNetwork = Network.Regtest;
375
+ break;
376
+ default:
377
+ throw new Error(
378
+ `Unsupported lightspark_crypto network ${this.network}.`
379
+ );
380
+ }
381
+ const lightsparkSigner = LightsparkSigner.from_bytes(
382
+ this.masterSeed,
383
+ cryptoLibNetwork
384
+ );
385
+ const privateKey = lightsparkSigner.derive_private_key(SIGNING_KEY_PATH);
386
+ return { key: privateKey, type: SigningKeyType.Secp256k1SigningKey };
387
+ }
388
+ };
389
+
390
+ // src/NodeKeyLoaderCache.ts
391
+ var NodeKeyLoaderCache = class {
392
+ constructor(nodeKeyCache, cryptoImpl = DefaultCrypto) {
393
+ this.nodeKeyCache = nodeKeyCache;
394
+ this.cryptoImpl = cryptoImpl;
395
+ this.idToLoader = /* @__PURE__ */ new Map();
396
+ }
397
+ idToLoader;
398
+ /**
399
+ * Sets the signing key loader for a node.
400
+ * Instantiates a signing key loader based on the type of args passed in by
401
+ * the user.
402
+ *
403
+ * @param nodeId The ID of the node to get the key for
404
+ * @param loaderArgs Loader arguments for loading the key
405
+ * @param requester Requester used for loading the key
406
+ */
407
+ setLoader(nodeId, loaderArgs, requester) {
408
+ let loader;
409
+ if (isNodeIdAndPasswordSigningKeyLoaderArgs(loaderArgs)) {
410
+ loader = new NodeIdAndPasswordSigningKeyLoader(
411
+ { nodeId, ...loaderArgs },
412
+ requester,
413
+ this.cryptoImpl
414
+ );
415
+ } else if (isMasterSeedSigningKeyLoaderArgs(loaderArgs)) {
416
+ loader = new MasterSeedSigningKeyLoader({ ...loaderArgs });
417
+ } else {
418
+ throw new LightsparkSigningException2("Invalid signing key loader args");
419
+ }
420
+ this.idToLoader.set(nodeId, loader);
421
+ }
422
+ /**
423
+ * Gets the key for a node using the loader set by [setLoader]
424
+ *
425
+ * @param id The ID of the node to get the key for
426
+ * @returns The loaded key
427
+ */
428
+ async getKeyWithLoader(id) {
429
+ if (this.nodeKeyCache.hasKey(id)) {
430
+ return this.nodeKeyCache.getKey(id);
431
+ }
432
+ const loader = this.idToLoader.get(id);
433
+ if (!loader) {
434
+ throw new LightsparkSigningException2(
435
+ "No signing key loader found for node " + id
436
+ );
437
+ }
438
+ const loaderResult = await loader.loadSigningKey();
439
+ if (!loaderResult) {
440
+ return;
441
+ }
442
+ const key = await this.nodeKeyCache.loadKey(
443
+ id,
444
+ { key: loaderResult.key },
445
+ loaderResult.type
446
+ );
447
+ return key || void 0;
263
448
  }
264
449
  };
265
450
 
@@ -686,6 +871,33 @@ var PayInvoice = `
686
871
  ${FRAGMENT9}
687
872
  `;
688
873
 
874
+ // src/graphql/PayUmaInvoice.ts
875
+ var PayUmaInvoice = `
876
+ mutation PayUmaInvoice(
877
+ $node_id: ID!
878
+ $encoded_invoice: String!
879
+ $timeout_secs: Int!
880
+ $maximum_fees_msats: Long!
881
+ $amount_msats: Long
882
+ ) {
883
+ pay_uma_invoice(
884
+ input: {
885
+ node_id: $node_id
886
+ encoded_invoice: $encoded_invoice
887
+ timeout_secs: $timeout_secs
888
+ maximum_fees_msats: $maximum_fees_msats
889
+ amount_msats: $amount_msats
890
+ }
891
+ ) {
892
+ payment {
893
+ ...OutgoingPaymentFragment
894
+ }
895
+ }
896
+ }
897
+
898
+ ${FRAGMENT9}
899
+ `;
900
+
689
901
  // src/graphql/PaymentRequestsForNode.ts
690
902
  var PaymentRequestsForNode = `
691
903
  query PaymentRequestsForNode(
@@ -717,33 +929,6 @@ query PaymentRequestsForNode(
717
929
  ${FRAGMENT10}
718
930
  `;
719
931
 
720
- // src/graphql/PayUmaInvoice.ts
721
- var PayUmaInvoice = `
722
- mutation PayUmaInvoice(
723
- $node_id: ID!
724
- $encoded_invoice: String!
725
- $timeout_secs: Int!
726
- $maximum_fees_msats: Long!
727
- $amount_msats: Long
728
- ) {
729
- pay_uma_invoice(
730
- input: {
731
- node_id: $node_id
732
- encoded_invoice: $encoded_invoice
733
- timeout_secs: $timeout_secs
734
- maximum_fees_msats: $maximum_fees_msats
735
- amount_msats: $amount_msats
736
- }
737
- ) {
738
- payment {
739
- ...OutgoingPaymentFragment
740
- }
741
- }
742
- }
743
-
744
- ${FRAGMENT9}
745
- `;
746
-
747
932
  // src/graphql/RequestWithdrawal.ts
748
933
  var RequestWithdrawal = `
749
934
  mutation RequestWithdrawal(
@@ -906,6 +1091,20 @@ ${FRAGMENT12}
906
1091
  ${FRAGMENT}
907
1092
  `;
908
1093
 
1094
+ // src/graphql/TransactionSubscription.ts
1095
+ var TransactionSubscription = `
1096
+ subscription TransactionSubscription(
1097
+ $nodeIds: [ID!]!
1098
+ ) {
1099
+ transactions(node_ids: $nodeIds) {
1100
+ ...TransactionUpdateFragment
1101
+ __typename
1102
+ }
1103
+ }
1104
+
1105
+ ${FRAGMENT13}
1106
+ `;
1107
+
909
1108
  // src/graphql/TransactionsForNode.ts
910
1109
  var TransactionsForNode = `
911
1110
  query TransactionsForNode(
@@ -945,204 +1144,6 @@ ${FRAGMENT12}
945
1144
  ${FRAGMENT}
946
1145
  `;
947
1146
 
948
- // src/graphql/TransactionSubscription.ts
949
- var TransactionSubscription = `
950
- subscription TransactionSubscription(
951
- $nodeIds: [ID!]!
952
- ) {
953
- transactions(node_ids: $nodeIds) {
954
- ...TransactionUpdateFragment
955
- __typename
956
- }
957
- }
958
-
959
- ${FRAGMENT13}
960
- `;
961
-
962
- // src/NodeKeyLoaderCache.ts
963
- import {
964
- DefaultCrypto,
965
- LightsparkSigningException as LightsparkSigningException2
966
- } from "@lightsparkdev/core";
967
-
968
- // src/SigningKeyLoader.ts
969
- import {
970
- b64encode as b64encode2,
971
- isBrowser,
972
- LightsparkSigningException,
973
- SigningKeyType
974
- } from "@lightsparkdev/core";
975
-
976
- // src/graphql/RecoverNodeSigningKey.ts
977
- var RecoverNodeSigningKey = `
978
- query RecoverNodeSigningKey($nodeId: ID!) {
979
- entity(id: $nodeId) {
980
- __typename
981
- ... on LightsparkNodeWithOSK {
982
- encrypted_signing_private_key {
983
- encrypted_value
984
- cipher
985
- }
986
- }
987
- }
988
- }
989
- `;
990
-
991
- // src/SigningKeyLoader.ts
992
- var SIGNING_KEY_PATH = "m/5";
993
- function isNodeIdAndPasswordSigningKeyLoaderArgs(args) {
994
- return args.password !== void 0;
995
- }
996
- function isMasterSeedSigningKeyLoaderArgs(args) {
997
- return args.masterSeed !== void 0;
998
- }
999
- var NodeIdAndPasswordSigningKeyLoader = class {
1000
- nodeId;
1001
- password;
1002
- requester;
1003
- cryptoImpl;
1004
- constructor(args, requester, cryptoImpl) {
1005
- this.nodeId = args.nodeId;
1006
- this.password = args.password;
1007
- this.requester = requester;
1008
- this.cryptoImpl = cryptoImpl;
1009
- }
1010
- async loadSigningKey() {
1011
- const encryptedKey = await this.recoverNodeSigningKey();
1012
- if (!encryptedKey) {
1013
- console.warn("No encrypted key found for node " + this.nodeId);
1014
- return;
1015
- }
1016
- const signingPrivateKey = await this.cryptoImpl.decryptSecretWithNodePassword(
1017
- encryptedKey.cipher,
1018
- encryptedKey.encrypted_value,
1019
- this.password
1020
- );
1021
- if (!signingPrivateKey) {
1022
- throw new LightsparkSigningException(
1023
- "Unable to decrypt signing key with provided password. Please try again."
1024
- );
1025
- }
1026
- let signingPrivateKeyPEM = "";
1027
- if (new Uint8Array(signingPrivateKey)[0] === 48) {
1028
- signingPrivateKeyPEM = b64encode2(signingPrivateKey);
1029
- } else {
1030
- const dec = new TextDecoder();
1031
- signingPrivateKeyPEM = dec.decode(signingPrivateKey);
1032
- }
1033
- return { key: signingPrivateKeyPEM, type: SigningKeyType.RSASigningKey };
1034
- }
1035
- async recoverNodeSigningKey() {
1036
- const response = await this.requester.makeRawRequest(
1037
- RecoverNodeSigningKey,
1038
- { nodeId: this.nodeId }
1039
- );
1040
- const nodeEntity = response.entity;
1041
- if (nodeEntity?.__typename === "LightsparkNodeWithOSK") {
1042
- return nodeEntity.encrypted_signing_private_key;
1043
- }
1044
- return null;
1045
- }
1046
- };
1047
- var MasterSeedSigningKeyLoader = class {
1048
- masterSeed;
1049
- network;
1050
- constructor(args) {
1051
- this.masterSeed = args.masterSeed;
1052
- this.network = args.network;
1053
- }
1054
- async loadSigningKey() {
1055
- if (isBrowser) {
1056
- throw new LightsparkSigningException(
1057
- "Browser environments not supported for master seed signing key loader."
1058
- );
1059
- }
1060
- const { LightsparkSigner, Network } = await import("@lightsparkdev/crypto-wasm");
1061
- let cryptoLibNetwork;
1062
- switch (this.network) {
1063
- case BitcoinNetwork_default.MAINNET:
1064
- cryptoLibNetwork = Network.Bitcoin;
1065
- break;
1066
- case BitcoinNetwork_default.TESTNET:
1067
- cryptoLibNetwork = Network.Testnet;
1068
- break;
1069
- case BitcoinNetwork_default.REGTEST:
1070
- cryptoLibNetwork = Network.Regtest;
1071
- break;
1072
- default:
1073
- throw new Error(
1074
- `Unsupported lightspark_crypto network ${this.network}.`
1075
- );
1076
- }
1077
- const lightsparkSigner = LightsparkSigner.from_bytes(
1078
- this.masterSeed,
1079
- cryptoLibNetwork
1080
- );
1081
- const privateKey = lightsparkSigner.derive_private_key(SIGNING_KEY_PATH);
1082
- return { key: privateKey, type: SigningKeyType.Secp256k1SigningKey };
1083
- }
1084
- };
1085
-
1086
- // src/NodeKeyLoaderCache.ts
1087
- var NodeKeyLoaderCache = class {
1088
- constructor(nodeKeyCache, cryptoImpl = DefaultCrypto) {
1089
- this.nodeKeyCache = nodeKeyCache;
1090
- this.cryptoImpl = cryptoImpl;
1091
- this.idToLoader = /* @__PURE__ */ new Map();
1092
- }
1093
- idToLoader;
1094
- /**
1095
- * Sets the signing key loader for a node.
1096
- * Instantiates a signing key loader based on the type of args passed in by the user.
1097
- *
1098
- * @param nodeId The ID of the node to get the key for
1099
- * @param loaderArgs Loader arguments for loading the key
1100
- * @param requester Requester used for loading the key
1101
- */
1102
- setLoader(nodeId, loaderArgs, requester) {
1103
- let loader;
1104
- if (isNodeIdAndPasswordSigningKeyLoaderArgs(loaderArgs)) {
1105
- loader = new NodeIdAndPasswordSigningKeyLoader(
1106
- { nodeId, ...loaderArgs },
1107
- requester,
1108
- this.cryptoImpl
1109
- );
1110
- } else if (isMasterSeedSigningKeyLoaderArgs(loaderArgs)) {
1111
- loader = new MasterSeedSigningKeyLoader({ ...loaderArgs });
1112
- } else {
1113
- throw new LightsparkSigningException2("Invalid signing key loader args");
1114
- }
1115
- this.idToLoader.set(nodeId, loader);
1116
- }
1117
- /**
1118
- * Gets the key for a node using the loader set by [setLoader]
1119
- *
1120
- * @param id The ID of the node to get the key for
1121
- * @returns The loaded key
1122
- */
1123
- async getKeyWithLoader(id) {
1124
- if (this.nodeKeyCache.hasKey(id)) {
1125
- return this.nodeKeyCache.getKey(id);
1126
- }
1127
- const loader = this.idToLoader.get(id);
1128
- if (!loader) {
1129
- throw new LightsparkSigningException2(
1130
- "No signing key loader found for node " + id
1131
- );
1132
- }
1133
- const loaderResult = await loader.loadSigningKey();
1134
- if (!loaderResult) {
1135
- return;
1136
- }
1137
- const key = await this.nodeKeyCache.loadKey(
1138
- id,
1139
- { key: loaderResult.key },
1140
- loaderResult.type
1141
- );
1142
- return key || void 0;
1143
- }
1144
- };
1145
-
1146
1147
  // src/client.ts
1147
1148
  var sdkVersion = package_default.version;
1148
1149
  var LightsparkClient = class {
@@ -1154,7 +1155,8 @@ var LightsparkClient = class {
1154
1155
  * use, you should use the `AccountTokenAuthProvider`.
1155
1156
  * @param serverUrl The base URL of the server to connect to. Defaults to lightspark production.
1156
1157
  * @param cryptoImpl The crypto implementation to use. Defaults to web and node compatible crypto.
1157
- * For React Native, you should use the `ReactNativeCrypto` implementation from `@lightsparkdev/react-native`.
1158
+ * For React Native, you should use the `ReactNativeCrypto`
1159
+ * implementation from `@lightsparkdev/react-native`.
1158
1160
  */
1159
1161
  constructor(authProvider = new StubAuthProvider(), serverUrl = "api.lightspark.com", cryptoImpl = DefaultCrypto2) {
1160
1162
  this.authProvider = authProvider;
@@ -1180,9 +1182,11 @@ var LightsparkClient = class {
1180
1182
  nodeKeyLoaderCache;
1181
1183
  LIGHTSPARK_SDK_ENDPOINT = process.env.LIGHTSPARK_SDK_ENDPOINT || "graphql/server/2023-09-13";
1182
1184
  /**
1183
- * Sets the key loader for a node. This unlocks client operations that require a private key.
1184
- * Passing in [NodeIdAndPasswordSigningKeyLoaderArgs] loads the RSA key for an OSK node.
1185
- * Passing in [MasterSeedSigningKeyLoaderArgs] loads the Secp256k1 key for a remote signing node.
1185
+ * Sets the key loader for a node. This unlocks client operations that
1186
+ * require a private key. Passing in [NodeIdAndPasswordSigningKeyLoaderArgs]
1187
+ * loads the RSA key for an OSK node.
1188
+ * Passing in [MasterSeedSigningKeyLoaderArgs] loads the Secp256k1 key for a
1189
+ * remote signing node.
1186
1190
  *
1187
1191
  * @param nodeId The ID of the node the key is for
1188
1192
  * @param loader The loader for the key
@@ -1193,7 +1197,8 @@ var LightsparkClient = class {
1193
1197
  return !!key;
1194
1198
  }
1195
1199
  /**
1196
- * Gets the signing key for a node. Must have previously called [loadNodeSigningKey].
1200
+ * Gets the signing key for a node. Must have previously called
1201
+ * [loadNodeSigningKey].
1197
1202
  *
1198
1203
  * @param nodeId The ID of the node the key is for
1199
1204
  * @returns The signing key for the node
@@ -1202,7 +1207,8 @@ var LightsparkClient = class {
1202
1207
  return await this.nodeKeyLoaderCache.getKeyWithLoader(nodeId);
1203
1208
  }
1204
1209
  /**
1205
- * Sets the auth provider for the client. This is useful for switching between auth providers if you are using
1210
+ * Sets the auth provider for the client.
1211
+ * This is useful for switching between auth providers if you are using
1206
1212
  * multiple accounts or waiting for the user to log in.
1207
1213
  *
1208
1214
  * @param authProvider
@@ -1281,7 +1287,8 @@ var LightsparkClient = class {
1281
1287
  ) ?? [];
1282
1288
  }
1283
1289
  /**
1284
- * Starts listening for new transactions or updates to existing transactions for a list of nodes.
1290
+ * Starts listening for new transactions or updates to existing transactions
1291
+ * for a list of nodes.
1285
1292
  *
1286
1293
  * @param nodeIds The node IDs for which to listen to transactions.
1287
1294
  * @returns A zen-observable that emits transaction updates for the given node IDs.
@@ -1298,8 +1305,8 @@ var LightsparkClient = class {
1298
1305
  );
1299
1306
  }
1300
1307
  /**
1301
- * Retrieves a dashboard of basic info for the authenticated account. See `AccountDashboard` for which info is
1302
- * included.
1308
+ * Retrieves a dashboard of basic info for the authenticated account.
1309
+ * See `AccountDashboard` for which info is included.
1303
1310
  *
1304
1311
  * @param nodeIds The node IDs to include in the dashboard. Defaults to undefined (all nodes).
1305
1312
  * @param bitcoinNetwork The bitcoin network to include in the dashboard. Defaults to MAINNET.
@@ -1366,8 +1373,8 @@ var LightsparkClient = class {
1366
1373
  };
1367
1374
  }
1368
1375
  /**
1369
- * Gets a basic dashboard for a single node, including recent transactions. See `SingleNodeDashboard` for which info is
1370
- * included.
1376
+ * Gets a basic dashboard for a single node, including recent transactions.
1377
+ * See `SingleNodeDashboard` for which info is included.
1371
1378
  *
1372
1379
  * @param nodeId The node ID for which to get a dashboard.
1373
1380
  * @param bitcoinNetwork The bitcoin network for which to get a dashboard. Defaults to MAINNET.
@@ -1438,7 +1445,8 @@ var LightsparkClient = class {
1438
1445
  /**
1439
1446
  * Creates an invoice for the given node.
1440
1447
  *
1441
- * Test mode note: You can simulate a payment of this invoice in test move using [createTestModePayment].
1448
+ * Test mode note: You can simulate a payment of this invoice in test move
1449
+ * using [createTestModePayment].
1442
1450
  *
1443
1451
  * @param nodeId The node ID for which to create an invoice.
1444
1452
  * @param amountMsats The amount of the invoice in msats. You can create a zero-amount invoice to accept any payment amount.
@@ -1466,11 +1474,13 @@ var LightsparkClient = class {
1466
1474
  return response.create_invoice?.invoice.data?.encoded_payment_request;
1467
1475
  }
1468
1476
  /**
1469
- * Generates a Lightning Invoice (follows the Bolt 11 specification) to request a payment
1470
- * from another Lightning Node. This should only be used for generating invoices for LNURLs,
1477
+ * Generates a Lightning Invoice (follows the Bolt 11 specification) to
1478
+ * request a payment from another Lightning Node.
1479
+ * This should only be used for generating invoices for LNURLs,
1471
1480
  * with [createInvoice] preferred in the general case.
1472
1481
  *
1473
- * Test mode note: You can simulate a payment of this invoice in test move using [createTestModePayment].
1482
+ * Test mode note: You can simulate a payment of this invoice in test move
1483
+ * using [createTestModePayment].
1474
1484
  *
1475
1485
  * @param nodeId The node ID for which to create an invoice.
1476
1486
  * @param amountMsats The amount of the invoice in msats. You can create a zero-amount invoice to accept any payment amount.
@@ -1501,10 +1511,12 @@ var LightsparkClient = class {
1501
1511
  return InvoiceFromJson(invoiceJson);
1502
1512
  }
1503
1513
  /**
1504
- * Creates a new invoice for the UMA protocol. The metadata is hashed and included in the invoice.
1505
- * This API generates a Lightning Invoice (follows the Bolt 11 specification) to request a payment
1506
- * from another Lightning Node. This should only be used for generating invoices for UMA, with `createInvoice`
1507
- * preferred in the general case.
1514
+ * Creates a new invoice for the UMA protocol.
1515
+ * The metadata is hashed and included in the invoice.
1516
+ * This API generates a Lightning Invoice (follows the Bolt 11 specification)
1517
+ * to request a payment from another Lightning Node.
1518
+ * This should only be used for generating invoices for UMA,
1519
+ * with `createInvoice` preferred in the general case.
1508
1520
  *
1509
1521
  * @param nodeId The node ID for which to create an invoice.
1510
1522
  * @param amountMsats The amount of the invoice in msats. You can create a zero-amount invoice to accept any payment amount.
@@ -1545,7 +1557,8 @@ var LightsparkClient = class {
1545
1557
  return InvoiceDataFromJson(response.decoded_payment_request);
1546
1558
  }
1547
1559
  /**
1548
- * Gets an estimate of the fee for sending a payment over the given bitcoin network.
1560
+ * Gets an estimate of the fee for sending a payment over the given bitcoin
1561
+ * network.
1549
1562
  *
1550
1563
  * @param bitcoinNetwork The bitcoin network for which to get a fee estimate. Defaults to MAINNET.
1551
1564
  * @returns A fee estimate for the given bitcoin network including a minimum fee rate, and a max-speed fee rate.
@@ -1582,7 +1595,8 @@ var LightsparkClient = class {
1582
1595
  );
1583
1596
  }
1584
1597
  /**
1585
- * Returns an estimate of the fees that will be paid to send a payment to another Lightning node.
1598
+ * Returns an estimate of the fees that will be paid to send a payment to
1599
+ * another Lightning node.
1586
1600
  *
1587
1601
  * @param nodeId The node from where you want to send the payment.
1588
1602
  * @param destinationNodePublicKey The public key of the node that you want to pay.
@@ -1618,17 +1632,20 @@ var LightsparkClient = class {
1618
1632
  /**
1619
1633
  * Sends a lightning payment for a given invoice.
1620
1634
  *
1621
- * Test mode note: For test mode, you can use the [createTestModeInvoice] function to create an invoice you can
1622
- * pay in test mode.
1635
+ * Test mode note: For test mode, you can use the [createTestModeInvoice]
1636
+ * function to create an invoice you can pay in test mode.
1623
1637
  *
1624
1638
  * @param payerNodeId The ID of the node that will pay the invoice.
1625
1639
  * @param encodedInvoice The encoded invoice to pay.
1626
1640
  * @param maximumFeesMsats Maximum fees (in msats) to pay for the payment. This parameter is required.
1627
- * As guidance, a maximum fee of 16 basis points should make almost all transactions succeed. For example,
1628
- * for a transaction between 10k sats and 100k sats, this would mean a fee limit of 16 to 160 sats.
1641
+ * As guidance, a maximum fee of 16 basis points should make almost all
1642
+ * transactions succeed. For example,
1643
+ * for a transaction between 10k sats and 100k sats,
1644
+ * this would mean a fee limit of 16 to 160 sats.
1629
1645
  * @param timeoutSecs A timeout for the payment in seconds. Defaults to 60 seconds.
1630
1646
  * @param amountMsats The amount to pay in msats for a zero-amount invoice. Defaults to the full amount of the
1631
- * invoice. NOTE: This parameter can only be passed for a zero-amount invoice. Otherwise, the call will fail.
1647
+ * invoice. NOTE: This parameter can only be passed for a zero-amount
1648
+ * invoice. Otherwise, the call will fail.
1632
1649
  * @returns An `OutgoingPayment` object if the payment was successful, or undefined if the payment failed.
1633
1650
  */
1634
1651
  async payInvoice(payerNodeId, encodedInvoice, maximumFeesMsats, timeoutSecs = 60, amountMsats = void 0) {
@@ -1658,18 +1675,23 @@ var LightsparkClient = class {
1658
1675
  return response.pay_invoice && OutgoingPaymentFromJson(response.pay_invoice.payment);
1659
1676
  }
1660
1677
  /**
1661
- * sends an UMA payment to a node on the Lightning Network, based on the invoice
1662
- * (as defined by the BOLT11 specification) that you provide.
1663
- * This should only be used for paying UMA invoices, with `payInvoice` preferred in the general case.
1678
+ * sends an UMA payment to a node on the Lightning Network,
1679
+ * based on the invoice (as defined by the BOLT11 specification) that you
1680
+ * provide.
1681
+ * This should only be used for paying UMA invoices,
1682
+ * with `payInvoice` preferred in the general case.
1664
1683
  *
1665
1684
  * @param payerNodeId The ID of the node that will pay the invoice.
1666
1685
  * @param encodedInvoice The encoded invoice to pay.
1667
1686
  * @param maximumFeesMsats Maximum fees (in msats) to pay for the payment. This parameter is required.
1668
- * As guidance, a maximum fee of 16 basis points should make almost all transactions succeed. For example,
1669
- * for a transaction between 10k sats and 100k sats, this would mean a fee limit of 16 to 160 sats.
1687
+ * As guidance, a maximum fee of 16 basis points should make almost all
1688
+ * transactions succeed. For example,
1689
+ * for a transaction between 10k sats and 100k sats,
1690
+ * this would mean a fee limit of 16 to 160 sats.
1670
1691
  * @param timeoutSecs A timeout for the payment in seconds. Defaults to 60 seconds.
1671
1692
  * @param amountMsats The amount to pay in msats for a zero-amount invoice. Defaults to the full amount of the
1672
- * invoice. NOTE: This parameter can only be passed for a zero-amount invoice. Otherwise, the call will fail.
1693
+ * invoice. NOTE: This parameter can only be passed for a zero-amount
1694
+ * invoice. Otherwise, the call will fail.
1673
1695
  * @returns An `OutgoingPayment` object if the payment was successful, or undefined if the payment failed.
1674
1696
  */
1675
1697
  async payUmaInvoice(payerNodeId, encodedInvoice, maximumFeesMsats, timeoutSecs = 60, amountMsats = void 0) {
@@ -1699,7 +1721,8 @@ var LightsparkClient = class {
1699
1721
  return response.pay_uma_invoice && OutgoingPaymentFromJson(response.pay_invoice.payment);
1700
1722
  }
1701
1723
  /**
1702
- * Waits for a transaction to have a completed status, and returns the transaction.
1724
+ * Waits for a transaction to have a completed status, and returns the
1725
+ * transaction.
1703
1726
  *
1704
1727
  * @param transactionId The ID of the transaction to wait for
1705
1728
  * @param pollTimeoutSecs The timeout in seconds that we will wait before throwing an exception
@@ -1736,15 +1759,18 @@ var LightsparkClient = class {
1736
1759
  return transaction;
1737
1760
  }
1738
1761
  /**
1739
- * Sends a payment directly to a node on the Lightning Network through the public key of the node without an invoice.
1762
+ * Sends a payment directly to a node on the Lightning Network through the
1763
+ * public key of the node without an invoice.
1740
1764
  *
1741
1765
  * @param payerNodeId The ID of the node that will send the payment.
1742
1766
  * @param destinationPublicKey The public key of the destination node.
1743
1767
  * @param timeoutSecs The timeout in seconds that we will try to make the payment.
1744
1768
  * @param amountMsats The amount to pay in msats.
1745
1769
  * @param maximumFeesMsats Maximum fees (in msats) to pay for the payment. This parameter is required.
1746
- * As guidance, a maximum fee of 15 basis points should make almost all transactions succeed. For example,
1747
- * for a transaction between 10k sats and 100k sats, this would mean a fee limit of 15 to 150 sats.
1770
+ * As guidance, a maximum fee of 15 basis points should make almost all
1771
+ * transactions succeed. For example,
1772
+ * for a transaction between 10k sats and 100k sats,
1773
+ * this would mean a fee limit of 15 to 150 sats.
1748
1774
  * @returns An `OutgoingPayment` object if the payment was successful, or undefined if the payment failed.
1749
1775
  */
1750
1776
  async sendPayment(payerNodeId, destinationPublicKey, timeoutSecs = 60, amountMsats, maximumFeesMsats) {
@@ -1771,7 +1797,8 @@ var LightsparkClient = class {
1771
1797
  return response.send_payment && OutgoingPaymentFromJson(response.send_payment.payment);
1772
1798
  }
1773
1799
  /**
1774
- * Creates an L1 Bitcoin wallet address for a given node which can be used to deposit or withdraw funds.
1800
+ * Creates an L1 Bitcoin wallet address for a given node which can be used to
1801
+ * deposit or withdraw funds.
1775
1802
  *
1776
1803
  * @param nodeId The ID of the node to create a wallet address for.
1777
1804
  * @returns A string containing the wallet address for the given node.
@@ -1784,12 +1811,15 @@ var LightsparkClient = class {
1784
1811
  return response.create_node_wallet_address.wallet_address;
1785
1812
  }
1786
1813
  /**
1787
- * Withdraws funds from the account and sends it to the requested bitcoin address.
1814
+ * Withdraws funds from the account and sends it to the requested bitcoin
1815
+ * address.
1788
1816
  *
1789
- * Depending on the chosen mode, it will first take the funds from the wallet, and if applicable, close channels
1790
- * appropriately to recover enough funds and reopen channels with the remaining funds.
1791
- * The process is asynchronous and may take up to a few minutes. You can check the progress by polling the
1792
- * `WithdrawalRequest` that is created, or by subscribing to a webhook.
1817
+ * Depending on the chosen mode, it will first take the funds from the
1818
+ * wallet, and if applicable, close channels appropriately to recover enough
1819
+ * funds and reopen channels with the remaining funds.
1820
+ * The process is asynchronous and may take up to a few minutes.
1821
+ * You can check the progress by polling the `WithdrawalRequest` that is
1822
+ * created, or by subscribing to a webhook.
1793
1823
  *
1794
1824
  * @param nodeId The ID of the node from which to withdraw funds.
1795
1825
  * @param amountSats The amount of funds to withdraw in satoshis.
@@ -1810,9 +1840,10 @@ var LightsparkClient = class {
1810
1840
  return WithdrawalRequestFromJson(response.request_withdrawal.request);
1811
1841
  }
1812
1842
  /**
1813
- * Adds funds to a Lightspark node on the REGTEST network. If the amount is not specified, 10,000,000 SATOSHI will be
1814
- * added. This API only functions for nodes created on the REGTEST network and will return an error when called for
1815
- * any non-REGTEST node.
1843
+ * Adds funds to a Lightspark node on the REGTEST network.
1844
+ * If the amount is not specified, 10,000,000 SATOSHI will be added.
1845
+ * This API only functions for nodes created on the REGTEST network and will
1846
+ * return an error when called for any non-REGTEST node.
1816
1847
  *
1817
1848
  * @param nodeId The ID of the node to fund. Must be a REGTEST node.
1818
1849
  * @param amountSats The amount of funds to add to the node in satoshis. Defaults to 10,000,000 SATOSHI.
@@ -1826,8 +1857,8 @@ var LightsparkClient = class {
1826
1857
  return CurrencyAmountFromJson(response.fund_node.amount);
1827
1858
  }
1828
1859
  /**
1829
- * Creates a new API token that can be used to authenticate requests for this account when using the Lightspark APIs
1830
- * and SDKs.
1860
+ * Creates a new API token that can be used to authenticate requests for this
1861
+ * account when using the Lightspark APIs and SDKs.
1831
1862
  *
1832
1863
  * @param name Creates a new API token that can be used to authenticate requests for this account when using the
1833
1864
  * Lightspark APIs and SDKs.
@@ -1864,8 +1895,9 @@ var LightsparkClient = class {
1864
1895
  await this.requester.makeRawRequest(DeleteApiToken, { api_token_id: id });
1865
1896
  }
1866
1897
  /**
1867
- * In test mode, generates a Lightning Invoice which can be paid by a local node.
1868
- * This call is only valid in test mode. You can then pay the invoice using [payInvoice].
1898
+ * In test mode, generates a Lightning Invoice which can be paid by a local
1899
+ * node. This call is only valid in test mode.
1900
+ * You can then pay the invoice using [payInvoice].
1869
1901
  *
1870
1902
  * @param localNodeId The ID of the node that will pay the invoice.
1871
1903
  * @param amountMsats The amount to pay in milli-satoshis.
@@ -1894,8 +1926,9 @@ var LightsparkClient = class {
1894
1926
  });
1895
1927
  }
1896
1928
  /**
1897
- * In test mode, simulates a payment of a Lightning Invoice from another node.
1898
- * This can only be used in test mode and should be used with invoices generated by [createInvoice].
1929
+ * In test mode, simulates a payment of a Lightning Invoice from another
1930
+ * node. This can only be used in test mode and should be used with invoices
1931
+ * generated by [createInvoice].
1899
1932
  *
1900
1933
  * @param localNodeId The ID of the node that will receive the payment.
1901
1934
  * @param encodedInvoice The encoded invoice to pay.
@@ -1918,8 +1951,8 @@ var LightsparkClient = class {
1918
1951
  });
1919
1952
  }
1920
1953
  /**
1921
- * Creates an UMA invitation. If you are part of the incentive program, you should use
1922
- * [createUmaInvitationWithIncentives].
1954
+ * Creates an UMA invitation. If you are part of the incentive program,
1955
+ * you should use [createUmaInvitationWithIncentives].
1923
1956
  *
1924
1957
  * @param inviterUma The UMA of the inviter.
1925
1958
  * @returns The invitation that was created.
@@ -1973,8 +2006,8 @@ var LightsparkClient = class {
1973
2006
  });
1974
2007
  }
1975
2008
  /**
1976
- * Claims an UMA invitation. If you are part of the incentive program, you should use
1977
- * [claimUmaInvitationWithIncentives].
2009
+ * Claims an UMA invitation. If you are part of the incentive program,
2010
+ * you should use [claimUmaInvitationWithIncentives].
1978
2011
  *
1979
2012
  * @param invitationCode The invitation code to claim.
1980
2013
  * @param inviteeUma The UMA of the invitee.
@@ -2065,7 +2098,8 @@ var LightsparkClient = class {
2065
2098
  /**
2066
2099
  * Executes a raw `Query` against the Lightspark API.
2067
2100
  *
2068
- * This generally should not be used directly, but is exposed for advanced use cases and for internal use to retrieve
2101
+ * This generally should not be used directly,
2102
+ * but is exposed for advanced use cases and for internal use to retrieve
2069
2103
  * complex fields from objects.
2070
2104
  *
2071
2105
  * @param query The `Query` to execute.