@ledgerhq/coin-module-framework 8.1.0 → 8.2.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.
Files changed (108) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/lib/api/impl.d.ts +74 -0
  3. package/lib/api/impl.d.ts.map +1 -0
  4. package/lib/api/impl.js +60 -0
  5. package/lib/api/impl.js.map +1 -0
  6. package/lib/api/index.d.ts +4 -0
  7. package/lib/api/index.d.ts.map +1 -1
  8. package/lib/api/index.js +4 -0
  9. package/lib/api/index.js.map +1 -1
  10. package/lib/api/notSupported.d.ts +14 -0
  11. package/lib/api/notSupported.d.ts.map +1 -1
  12. package/lib/api/notSupported.js +31 -2
  13. package/lib/api/notSupported.js.map +1 -1
  14. package/lib/api/notSupportedApi.d.ts +37 -0
  15. package/lib/api/notSupportedApi.d.ts.map +1 -0
  16. package/lib/api/notSupportedApi.js +68 -0
  17. package/lib/api/notSupportedApi.js.map +1 -0
  18. package/lib/api/withDefaults.d.ts +31 -0
  19. package/lib/api/withDefaults.d.ts.map +1 -0
  20. package/lib/api/withDefaults.js +57 -0
  21. package/lib/api/withDefaults.js.map +1 -0
  22. package/lib/api/wrappers/index.d.ts +17 -0
  23. package/lib/api/wrappers/index.d.ts.map +1 -0
  24. package/lib/api/wrappers/index.js +35 -0
  25. package/lib/api/wrappers/index.js.map +1 -0
  26. package/lib/api/wrappers/instrumenter.d.ts +27 -0
  27. package/lib/api/wrappers/instrumenter.d.ts.map +1 -0
  28. package/lib/api/wrappers/instrumenter.js +46 -0
  29. package/lib/api/wrappers/instrumenter.js.map +1 -0
  30. package/lib/api/wrappers/withLogging.d.ts +11 -0
  31. package/lib/api/wrappers/withLogging.d.ts.map +1 -0
  32. package/lib/api/wrappers/withLogging.js +40 -0
  33. package/lib/api/wrappers/withLogging.js.map +1 -0
  34. package/lib/api/wrappers/withTracing.d.ts +18 -0
  35. package/lib/api/wrappers/withTracing.d.ts.map +1 -0
  36. package/lib/api/wrappers/withTracing.js +40 -0
  37. package/lib/api/wrappers/withTracing.js.map +1 -0
  38. package/lib/test-utils/capabilities.d.ts +44 -0
  39. package/lib/test-utils/capabilities.d.ts.map +1 -0
  40. package/lib/test-utils/capabilities.js +44 -0
  41. package/lib/test-utils/capabilities.js.map +1 -0
  42. package/lib/test-utils/helpers.d.ts +1 -1
  43. package/lib/test-utils/helpers.d.ts.map +1 -1
  44. package/lib/test-utils/helpers.js +15 -0
  45. package/lib/test-utils/helpers.js.map +1 -1
  46. package/lib-es/api/impl.d.ts +74 -0
  47. package/lib-es/api/impl.d.ts.map +1 -0
  48. package/lib-es/api/impl.js +57 -0
  49. package/lib-es/api/impl.js.map +1 -0
  50. package/lib-es/api/index.d.ts +4 -0
  51. package/lib-es/api/index.d.ts.map +1 -1
  52. package/lib-es/api/index.js +4 -0
  53. package/lib-es/api/index.js.map +1 -1
  54. package/lib-es/api/notSupported.d.ts +14 -0
  55. package/lib-es/api/notSupported.d.ts.map +1 -1
  56. package/lib-es/api/notSupported.js +30 -2
  57. package/lib-es/api/notSupported.js.map +1 -1
  58. package/lib-es/api/notSupportedApi.d.ts +37 -0
  59. package/lib-es/api/notSupportedApi.d.ts.map +1 -0
  60. package/lib-es/api/notSupportedApi.js +65 -0
  61. package/lib-es/api/notSupportedApi.js.map +1 -0
  62. package/lib-es/api/withDefaults.d.ts +31 -0
  63. package/lib-es/api/withDefaults.d.ts.map +1 -0
  64. package/lib-es/api/withDefaults.js +54 -0
  65. package/lib-es/api/withDefaults.js.map +1 -0
  66. package/lib-es/api/wrappers/index.d.ts +17 -0
  67. package/lib-es/api/wrappers/index.d.ts.map +1 -0
  68. package/lib-es/api/wrappers/index.js +19 -0
  69. package/lib-es/api/wrappers/index.js.map +1 -0
  70. package/lib-es/api/wrappers/instrumenter.d.ts +27 -0
  71. package/lib-es/api/wrappers/instrumenter.d.ts.map +1 -0
  72. package/lib-es/api/wrappers/instrumenter.js +43 -0
  73. package/lib-es/api/wrappers/instrumenter.js.map +1 -0
  74. package/lib-es/api/wrappers/withLogging.d.ts +11 -0
  75. package/lib-es/api/wrappers/withLogging.d.ts.map +1 -0
  76. package/lib-es/api/wrappers/withLogging.js +37 -0
  77. package/lib-es/api/wrappers/withLogging.js.map +1 -0
  78. package/lib-es/api/wrappers/withTracing.d.ts +18 -0
  79. package/lib-es/api/wrappers/withTracing.d.ts.map +1 -0
  80. package/lib-es/api/wrappers/withTracing.js +37 -0
  81. package/lib-es/api/wrappers/withTracing.js.map +1 -0
  82. package/lib-es/test-utils/capabilities.d.ts +44 -0
  83. package/lib-es/test-utils/capabilities.d.ts.map +1 -0
  84. package/lib-es/test-utils/capabilities.js +41 -0
  85. package/lib-es/test-utils/capabilities.js.map +1 -0
  86. package/lib-es/test-utils/helpers.d.ts +1 -1
  87. package/lib-es/test-utils/helpers.d.ts.map +1 -1
  88. package/lib-es/test-utils/helpers.js +1 -0
  89. package/lib-es/test-utils/helpers.js.map +1 -1
  90. package/package.json +1 -1
  91. package/src/api/impl.test.ts +83 -0
  92. package/src/api/impl.ts +112 -0
  93. package/src/api/index.ts +4 -0
  94. package/src/api/notSupported.ts +32 -2
  95. package/src/api/notSupportedApi.test.ts +67 -0
  96. package/src/api/notSupportedApi.ts +74 -0
  97. package/src/api/withDefaults.test.ts +190 -0
  98. package/src/api/withDefaults.ts +87 -0
  99. package/src/api/wrappers/index.ts +20 -0
  100. package/src/api/wrappers/instrumenter.test.ts +123 -0
  101. package/src/api/wrappers/instrumenter.ts +58 -0
  102. package/src/api/wrappers/withLogging.test.ts +137 -0
  103. package/src/api/wrappers/withLogging.ts +47 -0
  104. package/src/api/wrappers/withTracing.test.ts +125 -0
  105. package/src/api/wrappers/withTracing.ts +56 -0
  106. package/src/test-utils/capabilities.test.ts +108 -0
  107. package/src/test-utils/capabilities.ts +93 -0
  108. package/src/test-utils/helpers.ts +2 -0
@@ -1,13 +1,41 @@
1
1
  // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
2
  // SPDX-License-Identifier: Apache-2.0
3
+ /**
4
+ * Marks a function as a framework-built "not supported" stub.
5
+ *
6
+ * `Symbol.for` (the global registry) is used deliberately: in a monorepo the framework
7
+ * may be present as more than one physical module instance, and a locally-scoped symbol
8
+ * would not match across them.
9
+ */
10
+ const NOT_SUPPORTED_STUB = Symbol.for('@ledgerhq/coin-module-framework:notSupportedStub');
3
11
  /**
4
12
  * Build a {@link CoinModuleApi} method stub that always throws a standardized
5
13
  * "not supported" error. Use it for optional API methods a module does not implement.
6
14
  *
15
+ * The returned function is tagged so the framework can tell it apart from a real
16
+ * implementation — see {@link isNotSupportedStub}.
17
+ *
7
18
  * @param name the API method name, used in the error message
8
19
  * @returns a function that throws `"<name> is not supported"` when invoked
9
20
  */
10
- export const notSupported = (name) => () => {
11
- throw new Error(`${name} is not supported`);
21
+ export const notSupported = (name) => {
22
+ const stub = () => {
23
+ throw new Error(`${name} is not supported`);
24
+ };
25
+ Object.defineProperty(stub, NOT_SUPPORTED_STUB, { value: true, enumerable: false });
26
+ return stub;
12
27
  };
28
+ /**
29
+ * Tells whether a value is a stub produced by {@link notSupported}, i.e. a placeholder
30
+ * rather than a real implementation.
31
+ *
32
+ * **Limitation** — only stubs built by {@link notSupported} are detectable. A module that
33
+ * hand-rolls `() => { throw new Error('x is not supported') }` inline is indistinguishable
34
+ * from a real implementation, because whether a function throws cannot be known without
35
+ * calling it. Modules should therefore either omit an unsupported method entirely (the
36
+ * migrated shape) or build its stub with {@link notSupported}.
37
+ */
38
+ export function isNotSupportedStub(value) {
39
+ return typeof value === 'function' && NOT_SUPPORTED_STUB in value;
40
+ }
13
41
  //# sourceMappingURL=notSupported.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"notSupported.js","sourceRoot":"","sources":["../../src/api/notSupported.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,GAAU,EAAE;IACxD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAA;AAC7C,CAAC,CAAA"}
1
+ {"version":3,"file":"notSupported.js","sourceRoot":"","sources":["../../src/api/notSupported.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAEtC;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,MAAM,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAA;AAEzF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,EAAE;IAC3C,MAAM,IAAI,GAAG,GAAU,EAAE;QACvB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAA;IAC7C,CAAC,CAAA;IACD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAA;IACnF,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,OAAO,KAAK,KAAK,UAAU,IAAI,kBAAkB,IAAI,KAAK,CAAA;AACnE,CAAC"}
@@ -0,0 +1,37 @@
1
+ import type { CurrencyConfig } from '../config';
2
+ import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from './types';
3
+ /**
4
+ * A full {@link CoinModuleApi} whose every capability is a "not supported" stub.
5
+ *
6
+ * Spread it and override what the chain does support, for a module that would rather
7
+ * satisfy the complete contract directly than declare a `CoinModuleImpl` and be widened by
8
+ * `withDefaults`:
9
+ *
10
+ * ```ts
11
+ * export function createApi() {
12
+ * return {
13
+ * ...notSupportedApi<MyConfig>(),
14
+ * lastBlock, getBalance, listOperations,
15
+ * } satisfies CoinModuleApi<MyConfig>
16
+ * }
17
+ * ```
18
+ *
19
+ * The two styles interoperate rather than compete, because the stubs are tagged: a value
20
+ * built this way still tells the truth through `withDefaults`'s `supports()`, which treats a
21
+ * tagged stub as an omitted method rather than as an implementation. So a module may be
22
+ * authored either way, wrapped either way, and reports the same capabilities.
23
+ *
24
+ * It is also what a module can use when it does not implement everything the authoring type
25
+ * requires — a read-only module, or a chain with no crafting path. The contract is satisfied
26
+ * statically, and what the chain does not do stays visible at the definition site.
27
+ *
28
+ * `getAccountInfo` is the one method that does not throw: per ADR-045 a chain carrying no
29
+ * extra account metadata is an answer, not a missing capability, so it resolves the
30
+ * `{ type: 'none' }` sentinel — the same default `withDefaults` supplies. `listFeeOptions` is
31
+ * left absent, likewise matching `withDefaults`.
32
+ *
33
+ * The return type is the contract itself, so a method added to `CoinModuleApi` makes this
34
+ * fail to compile until it is covered here.
35
+ */
36
+ export declare function notSupportedApi<ConfigType extends CurrencyConfig, MemoType extends Memo = MemoNotSupported, TxDataType extends TxData = TxDataNotSupported>(): CoinModuleApi<ConfigType, MemoType, TxDataType>;
37
+ //# sourceMappingURL=notSupportedApi.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"notSupportedApi.d.ts","sourceRoot":"","sources":["../../src/api/notSupportedApi.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAGhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAC7B,UAAU,SAAS,cAAc,EACjC,QAAQ,SAAS,IAAI,GAAG,gBAAgB,EACxC,UAAU,SAAS,MAAM,GAAG,kBAAkB,KAC3C,aAAa,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CA6BnD"}
@@ -0,0 +1,65 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { notSupported } from './notSupported';
4
+ /**
5
+ * A full {@link CoinModuleApi} whose every capability is a "not supported" stub.
6
+ *
7
+ * Spread it and override what the chain does support, for a module that would rather
8
+ * satisfy the complete contract directly than declare a `CoinModuleImpl` and be widened by
9
+ * `withDefaults`:
10
+ *
11
+ * ```ts
12
+ * export function createApi() {
13
+ * return {
14
+ * ...notSupportedApi<MyConfig>(),
15
+ * lastBlock, getBalance, listOperations,
16
+ * } satisfies CoinModuleApi<MyConfig>
17
+ * }
18
+ * ```
19
+ *
20
+ * The two styles interoperate rather than compete, because the stubs are tagged: a value
21
+ * built this way still tells the truth through `withDefaults`'s `supports()`, which treats a
22
+ * tagged stub as an omitted method rather than as an implementation. So a module may be
23
+ * authored either way, wrapped either way, and reports the same capabilities.
24
+ *
25
+ * It is also what a module can use when it does not implement everything the authoring type
26
+ * requires — a read-only module, or a chain with no crafting path. The contract is satisfied
27
+ * statically, and what the chain does not do stays visible at the definition site.
28
+ *
29
+ * `getAccountInfo` is the one method that does not throw: per ADR-045 a chain carrying no
30
+ * extra account metadata is an answer, not a missing capability, so it resolves the
31
+ * `{ type: 'none' }` sentinel — the same default `withDefaults` supplies. `listFeeOptions` is
32
+ * left absent, likewise matching `withDefaults`.
33
+ *
34
+ * The return type is the contract itself, so a method added to `CoinModuleApi` makes this
35
+ * fail to compile until it is covered here.
36
+ */
37
+ export function notSupportedApi() {
38
+ return {
39
+ // Required by the authoring type — a module spreading this one must override them to
40
+ // be functional at all; they are stubbed here so the contract is satisfied statically.
41
+ lastBlock: notSupported('lastBlock'),
42
+ getBalance: notSupported('getBalance'),
43
+ listOperations: notSupported('listOperations'),
44
+ craftTransaction: notSupported('craftTransaction'),
45
+ estimateFees: notSupported('estimateFees'),
46
+ combine: notSupported('combine'),
47
+ broadcast: notSupported('broadcast'),
48
+ craftTransactionData: notSupported('craftTransactionData'),
49
+ // Optional capabilities.
50
+ getBlock: notSupported('getBlock'),
51
+ getBlockInfo: notSupported('getBlockInfo'),
52
+ getStakes: notSupported('getStakes'),
53
+ getRewards: notSupported('getRewards'),
54
+ getValidators: notSupported('getValidators'),
55
+ call: notSupported('call'),
56
+ craftRawTransaction: notSupported('craftRawTransaction'),
57
+ register: notSupported('register'),
58
+ getNextSequence: notSupported('getNextSequence'),
59
+ validateIntent: notSupported('validateIntent'),
60
+ validateAddress: notSupported('validateAddress'),
61
+ // Not a capability: absent metadata is an answer (ADR-045).
62
+ getAccountInfo: () => Promise.resolve({ type: 'none' }),
63
+ };
64
+ }
65
+ //# sourceMappingURL=notSupportedApi.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"notSupportedApi.js","sourceRoot":"","sources":["../../src/api/notSupportedApi.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAItC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,eAAe;IAK7B,OAAO;QACL,qFAAqF;QACrF,uFAAuF;QACvF,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC;QACpC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC;QACtC,cAAc,EAAE,YAAY,CAAC,gBAAgB,CAAC;QAC9C,gBAAgB,EAAE,YAAY,CAAC,kBAAkB,CAAC;QAClD,YAAY,EAAE,YAAY,CAAC,cAAc,CAAC;QAC1C,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC;QAChC,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC;QACpC,oBAAoB,EAAE,YAAY,CAAC,sBAAsB,CAAC;QAE1D,yBAAyB;QACzB,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC;QAClC,YAAY,EAAE,YAAY,CAAC,cAAc,CAAC;QAC1C,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC;QACpC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC;QACtC,aAAa,EAAE,YAAY,CAAC,eAAe,CAAC;QAC5C,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC;QAC1B,mBAAmB,EAAE,YAAY,CAAC,qBAAqB,CAAC;QACxD,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC;QAClC,eAAe,EAAE,YAAY,CAAC,iBAAiB,CAAC;QAChD,cAAc,EAAE,YAAY,CAAC,gBAAgB,CAAC;QAC9C,eAAe,EAAE,YAAY,CAAC,iBAAiB,CAAC;QAEhD,4DAA4D;QAC5D,cAAc,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACxD,CAAA;AACH,CAAC"}
@@ -0,0 +1,31 @@
1
+ import type { CurrencyConfig } from '../config';
2
+ import type { CoinModuleImpl, OptionalApiKey } from './impl';
3
+ import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from './types';
4
+ /**
5
+ * What {@link withDefaults} returns: the full consumer contract, plus `supports()`.
6
+ *
7
+ * `getAccountInfo` is narrowed to required. It is the one managed capability that
8
+ * {@link CoinModuleApi} itself declares optional, and `withDefaults` always supplies it — so
9
+ * callers can invoke it without a non-null assertion, and read `type` to tell a real answer from
10
+ * the `{ type: 'none' }` sentinel.
11
+ */
12
+ export type WithDefaultsResult<ConfigType extends CurrencyConfig, MemoType extends Memo = MemoNotSupported, TxDataType extends TxData = TxDataNotSupported> = CoinModuleApi<ConfigType, MemoType, TxDataType> & Required<Pick<CoinModuleApi<ConfigType, MemoType, TxDataType>, 'getAccountInfo'>> & {
13
+ supports: (method: OptionalApiKey) => boolean;
14
+ };
15
+ /**
16
+ * Widens a {@link CoinModuleImpl} authoring value to the full {@link CoinModuleApi}
17
+ * consumer contract by backfilling the capability methods the author omitted, and attaches
18
+ * a `supports()` introspection helper.
19
+ *
20
+ * Default per omitted method:
21
+ * - `getAccountInfo` → a `{ type: 'none' }` sentinel (ADR-045): having no extra account
22
+ * metadata is an answer, so callers get one instead of an exception.
23
+ * - every other capability → `notSupported(name)`, which throws `"<name> is not supported"`.
24
+ *
25
+ * Properties the authoring object carries beyond the API surface are preserved.
26
+ *
27
+ * A capability method is considered implemented only when the author supplied a real
28
+ * function — a `notSupported()` stub is treated as if the method had been omitted.
29
+ */
30
+ export declare function withDefaults<ConfigType extends CurrencyConfig, MemoType extends Memo = MemoNotSupported, TxDataType extends TxData = TxDataNotSupported, Extra extends object = Record<never, never>>(impl: CoinModuleImpl<ConfigType, MemoType, TxDataType> & Extra): WithDefaultsResult<ConfigType, MemoType, TxDataType> & Extra;
31
+ //# sourceMappingURL=withDefaults.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"withDefaults.d.ts","sourceRoot":"","sources":["../../src/api/withDefaults.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAIhG;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,CAC5B,UAAU,SAAS,cAAc,EACjC,QAAQ,SAAS,IAAI,GAAG,gBAAgB,EACxC,UAAU,SAAS,MAAM,GAAG,kBAAkB,IAC5C,aAAa,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,GACjD,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,gBAAgB,CAAC,CAAC,GAAG;IAClF,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAA;CAC9C,CAAA;AAaH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,UAAU,SAAS,cAAc,EACjC,QAAQ,SAAS,IAAI,GAAG,gBAAgB,EACxC,UAAU,SAAS,MAAM,GAAG,kBAAkB,EAC9C,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE3C,IAAI,EAAE,cAAc,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,KAAK,GAC7D,kBAAkB,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,KAAK,CA2B9D"}
@@ -0,0 +1,54 @@
1
+ // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { optionalApiKeys } from './impl';
4
+ import { isNotSupportedStub, notSupported } from './notSupported';
5
+ /**
6
+ * Normalizes an authored capability method to "present" or "absent".
7
+ *
8
+ * A `notSupported()` stub counts as absent: it is a placeholder, not an implementation,
9
+ * so the framework's own default takes over. Behavior is unchanged either way (both throw
10
+ * the same `"<name> is not supported"`), but `supports()` then reports the truth.
11
+ */
12
+ function implemented(value) {
13
+ return value === undefined || isNotSupportedStub(value) ? undefined : value;
14
+ }
15
+ /**
16
+ * Widens a {@link CoinModuleImpl} authoring value to the full {@link CoinModuleApi}
17
+ * consumer contract by backfilling the capability methods the author omitted, and attaches
18
+ * a `supports()` introspection helper.
19
+ *
20
+ * Default per omitted method:
21
+ * - `getAccountInfo` → a `{ type: 'none' }` sentinel (ADR-045): having no extra account
22
+ * metadata is an answer, so callers get one instead of an exception.
23
+ * - every other capability → `notSupported(name)`, which throws `"<name> is not supported"`.
24
+ *
25
+ * Properties the authoring object carries beyond the API surface are preserved.
26
+ *
27
+ * A capability method is considered implemented only when the author supplied a real
28
+ * function — a `notSupported()` stub is treated as if the method had been omitted.
29
+ */
30
+ export function withDefaults(impl) {
31
+ const implementedMethods = new Set(optionalApiKeys.filter((k) => implemented(impl[k]) !== undefined));
32
+ // Spread first so anything the module exposes beyond the API surface survives, then
33
+ // override every capability method with either the real implementation or the default.
34
+ return {
35
+ ...impl,
36
+ getBlock: implemented(impl.getBlock) ?? notSupported('getBlock'),
37
+ getBlockInfo: implemented(impl.getBlockInfo) ?? notSupported('getBlockInfo'),
38
+ getStakes: implemented(impl.getStakes) ?? notSupported('getStakes'),
39
+ getRewards: implemented(impl.getRewards) ?? notSupported('getRewards'),
40
+ getValidators: implemented(impl.getValidators) ?? notSupported('getValidators'),
41
+ call: implemented(impl.call) ?? notSupported('call'),
42
+ craftRawTransaction: implemented(impl.craftRawTransaction) ?? notSupported('craftRawTransaction'),
43
+ register: implemented(impl.register) ?? notSupported('register'),
44
+ getNextSequence: implemented(impl.getNextSequence) ?? notSupported('getNextSequence'),
45
+ validateIntent: implemented(impl.validateIntent) ?? notSupported('validateIntent'),
46
+ validateAddress: implemented(impl.validateAddress) ?? notSupported('validateAddress'),
47
+ // ADR-045: an absent getAccountInfo means the chain has no extra account metadata to
48
+ // report, which is an answer rather than a missing capability — hence a sentinel instead
49
+ // of a throwing stub. Callers read `type` and branch on it.
50
+ getAccountInfo: implemented(impl.getAccountInfo) ?? (() => Promise.resolve({ type: 'none' })),
51
+ supports: (method) => implementedMethods.has(method),
52
+ };
53
+ }
54
+ //# sourceMappingURL=withDefaults.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"withDefaults.js","sourceRoot":"","sources":["../../src/api/withDefaults.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAKtC,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAmBjE;;;;;;GAMG;AACH,SAAS,WAAW,CAAI,KAAoB;IAC1C,OAAO,KAAK,KAAK,SAAS,IAAI,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAA;AAC7E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAM1B,IAA8D;IAE9D,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAChC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAClE,CAAA;IAED,oFAAoF;IACpF,uFAAuF;IACvF,OAAO;QACL,GAAG,IAAI;QACP,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC,UAAU,CAAC;QAChE,YAAY,EAAE,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,cAAc,CAAC;QAC5E,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,YAAY,CAAC,WAAW,CAAC;QACnE,UAAU,EAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC;QACtE,aAAa,EAAE,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,YAAY,CAAC,eAAe,CAAC;QAC/E,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC;QACpD,mBAAmB,EACjB,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,YAAY,CAAC,qBAAqB,CAAC;QAC9E,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC,UAAU,CAAC;QAChE,eAAe,EAAE,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,YAAY,CAAC,iBAAiB,CAAC;QACrF,cAAc,EAAE,WAAW,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,YAAY,CAAC,gBAAgB,CAAC;QAClF,eAAe,EAAE,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,YAAY,CAAC,iBAAiB,CAAC;QACrF,qFAAqF;QACrF,yFAAyF;QACzF,4DAA4D;QAC5D,cAAc,EAAE,WAAW,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7F,QAAQ,EAAE,CAAC,MAAsB,EAAW,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC;KAC9E,CAAA;AACH,CAAC"}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Composable cross-cutting wrappers over a {@link CoinModuleApi}.
3
+ *
4
+ * Each takes a full API and returns one with identical generics, so they compose in any
5
+ * order and none of them belongs to the core contract: a consumer that wants no
6
+ * instrumentation never reaches this folder.
7
+ *
8
+ * That signature is the line between this folder and the core. `withDefaults` shares the
9
+ * `with*` name but stays in the core because it *changes* the type — it widens an authoring
10
+ * `CoinModuleImpl` into the `CoinModuleApi` consumers require, which is the adapter the
11
+ * authoring type exists for and not an optional concern. Anything that preserves the
12
+ * contract it receives belongs here; anything that produces it belongs in the core.
13
+ */
14
+ export * from './instrumenter';
15
+ export * from './withLogging';
16
+ export * from './withTracing';
17
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/wrappers/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA"}
@@ -0,0 +1,19 @@
1
+ // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ /**
4
+ * Composable cross-cutting wrappers over a {@link CoinModuleApi}.
5
+ *
6
+ * Each takes a full API and returns one with identical generics, so they compose in any
7
+ * order and none of them belongs to the core contract: a consumer that wants no
8
+ * instrumentation never reaches this folder.
9
+ *
10
+ * That signature is the line between this folder and the core. `withDefaults` shares the
11
+ * `with*` name but stays in the core because it *changes* the type — it widens an authoring
12
+ * `CoinModuleImpl` into the `CoinModuleApi` consumers require, which is the adapter the
13
+ * authoring type exists for and not an optional concern. Anything that preserves the
14
+ * contract it receives belongs here; anything that produces it belongs in the core.
15
+ */
16
+ export * from './instrumenter';
17
+ export * from './withLogging';
18
+ export * from './withTracing';
19
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/wrappers/index.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAEtC;;;;;;;;;;;;GAYG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA"}
@@ -0,0 +1,27 @@
1
+ import type { CurrencyConfig } from '../../config';
2
+ import type { CoinModuleApi, Memo, TxData } from '../types';
3
+ /**
4
+ * Returns a copy of a {@link CoinModuleApi} whose contract methods route through the
5
+ * provided `instrument` function. Everything else the object carries — non-API members
6
+ * such as the legacy bridge surface, or `supports` — is copied over untouched.
7
+ *
8
+ * Exported so other wrappers (withLogging, withTracing, withMetrics, …) can reuse the
9
+ * same interception mechanism without duplicating the boilerplate.
10
+ *
11
+ * The wrapped set is {@link apiMethodKeys}, the contract's own method list, rather than
12
+ * "every property that happens to be a function": what gets instrumented is then readable
13
+ * from the source, and a method added to the contract cannot be silently skipped — the
14
+ * exhaustiveness guard next to that list fails to compile first.
15
+ *
16
+ * Each method is wrapped and bound once, eagerly, so repeated reads are referentially
17
+ * stable (`api.getBalance === api.getBalance`) — a consumer using a method as a dependency
18
+ * key, a React effect or a memo cache, would otherwise see a new function every time — and
19
+ * no allocation happens on the call path.
20
+ *
21
+ * Expects a plain object, which is what a `createApi()` result and a `withDefaults` result
22
+ * both are. Methods living on a prototype rather than on the object itself are copied by
23
+ * value here, so a class instance that reassigns its own methods after wrapping would not
24
+ * see the change.
25
+ */
26
+ export declare function instrumentApi<C extends CurrencyConfig, M extends Memo, T extends TxData, Extra extends object = Record<never, never>>(api: CoinModuleApi<C, M, T> & Extra, instrument: (name: string, fn: (...args: unknown[]) => unknown, args: unknown[]) => unknown): CoinModuleApi<C, M, T> & Extra;
27
+ //# sourceMappingURL=instrumenter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"instrumenter.d.ts","sourceRoot":"","sources":["../../../src/api/wrappers/instrumenter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAO3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,cAAc,EACxB,CAAC,SAAS,IAAI,EACd,CAAC,SAAS,MAAM,EAChB,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE3C,GAAG,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,EACnC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAC1F,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAehC"}
@@ -0,0 +1,43 @@
1
+ // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { apiMethodKeys } from '../impl';
4
+ /** Narrows a copied member to a callable without asserting its type. */
5
+ const isMethod = (value) => typeof value === 'function';
6
+ /**
7
+ * Returns a copy of a {@link CoinModuleApi} whose contract methods route through the
8
+ * provided `instrument` function. Everything else the object carries — non-API members
9
+ * such as the legacy bridge surface, or `supports` — is copied over untouched.
10
+ *
11
+ * Exported so other wrappers (withLogging, withTracing, withMetrics, …) can reuse the
12
+ * same interception mechanism without duplicating the boilerplate.
13
+ *
14
+ * The wrapped set is {@link apiMethodKeys}, the contract's own method list, rather than
15
+ * "every property that happens to be a function": what gets instrumented is then readable
16
+ * from the source, and a method added to the contract cannot be silently skipped — the
17
+ * exhaustiveness guard next to that list fails to compile first.
18
+ *
19
+ * Each method is wrapped and bound once, eagerly, so repeated reads are referentially
20
+ * stable (`api.getBalance === api.getBalance`) — a consumer using a method as a dependency
21
+ * key, a React effect or a memo cache, would otherwise see a new function every time — and
22
+ * no allocation happens on the call path.
23
+ *
24
+ * Expects a plain object, which is what a `createApi()` result and a `withDefaults` result
25
+ * both are. Methods living on a prototype rather than on the object itself are copied by
26
+ * value here, so a class instance that reassigns its own methods after wrapping would not
27
+ * see the change.
28
+ */
29
+ export function instrumentApi(api, instrument) {
30
+ const instrumented = { ...api };
31
+ for (const name of apiMethodKeys) {
32
+ const method = instrumented[name];
33
+ // A contract method the object does not carry: `listFeeOptions`, which withDefaults
34
+ // leaves absent, or any method on a value that never went through withDefaults.
35
+ if (!isMethod(method))
36
+ continue;
37
+ const bound = method.bind(api);
38
+ instrumented[name] = (...args) => instrument(name, bound, args);
39
+ }
40
+ // oxlint-disable-next-line consistent-type-assertions -- every contract method was replaced by a wrapper of the same arity and the rest was copied verbatim, so the shape is unchanged; TS cannot follow that through an index-signature write
41
+ return instrumented;
42
+ }
43
+ //# sourceMappingURL=instrumenter.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"instrumenter.js","sourceRoot":"","sources":["../../../src/api/wrappers/instrumenter.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAItC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAEvC,wEAAwE;AACxE,MAAM,QAAQ,GAAG,CAAC,KAAc,EAA4C,EAAE,CAC5E,OAAO,KAAK,KAAK,UAAU,CAAA;AAE7B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,aAAa,CAM3B,GAAmC,EACnC,UAA2F;IAE3F,MAAM,YAAY,GAA4B,EAAE,GAAG,GAAG,EAAE,CAAA;IAExD,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QACjC,oFAAoF;QACpF,gFAAgF;QAChF,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,SAAQ;QAE/B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC9B,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAe,EAAW,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;IACrF,CAAC;IAED,+OAA+O;IAC/O,OAAO,YAA8C,CAAA;AACvD,CAAC"}
@@ -0,0 +1,11 @@
1
+ import type { CurrencyConfig } from '../../config';
2
+ import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from '../types';
3
+ /**
4
+ * Wraps a {@link CoinModuleApi} to emit log entries via the per-call {@link Context}'s
5
+ * logger before and after each method invocation, including on error.
6
+ *
7
+ * The Context is forwarded unchanged to the underlying method.
8
+ * Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
9
+ */
10
+ export declare function withLogging<C extends CurrencyConfig, M extends Memo = MemoNotSupported, T extends TxData = TxDataNotSupported, Extra extends object = Record<never, never>>(api: CoinModuleApi<C, M, T> & Extra): CoinModuleApi<C, M, T> & Extra;
11
+ //# sourceMappingURL=withLogging.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"withLogging.d.ts","sourceRoot":"","sources":["../../../src/api/wrappers/withLogging.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAGjG;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,CAAC,SAAS,cAAc,EACxB,CAAC,SAAS,IAAI,GAAG,gBAAgB,EACjC,CAAC,SAAS,MAAM,GAAG,kBAAkB,EACrC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC3C,GAAG,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CA2BrE"}
@@ -0,0 +1,37 @@
1
+ // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { instrumentApi } from './instrumenter';
4
+ /**
5
+ * Wraps a {@link CoinModuleApi} to emit log entries via the per-call {@link Context}'s
6
+ * logger before and after each method invocation, including on error.
7
+ *
8
+ * The Context is forwarded unchanged to the underlying method.
9
+ * Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
10
+ */
11
+ export function withLogging(api) {
12
+ return instrumentApi(api, (name, fn, args) => {
13
+ // oxlint-disable-next-line consistent-type-assertions -- args[0] is always Context<C> per CoinModuleApi contract; unknown cast needed to access logger
14
+ const logger = args[0]?.logger;
15
+ logger?.(`[coin-module] ${name}: call`);
16
+ let result;
17
+ try {
18
+ result = fn(...args);
19
+ }
20
+ catch (e) {
21
+ logger?.(`[coin-module] ${name}: error`, e);
22
+ throw e;
23
+ }
24
+ if (result instanceof Promise) {
25
+ return result.then((v) => {
26
+ logger?.(`[coin-module] ${name}: ok`);
27
+ return v;
28
+ }, (e) => {
29
+ logger?.(`[coin-module] ${name}: error`, e);
30
+ throw e;
31
+ });
32
+ }
33
+ logger?.(`[coin-module] ${name}: ok`);
34
+ return result;
35
+ });
36
+ }
37
+ //# sourceMappingURL=withLogging.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"withLogging.js","sourceRoot":"","sources":["../../../src/api/wrappers/withLogging.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAItC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAKzB,GAAmC;IACnC,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QAC3C,uJAAuJ;QACvJ,MAAM,MAAM,GAAI,IAAI,CAAC,CAAC,CAA4B,EAAE,MAAM,CAAA;QAC1D,MAAM,EAAE,CAAC,iBAAiB,IAAI,QAAQ,CAAC,CAAA;QACvC,IAAI,MAAe,CAAA;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,EAAE,CAAC,iBAAiB,IAAI,SAAS,EAAE,CAAC,CAAC,CAAA;YAC3C,MAAM,CAAC,CAAA;QACT,CAAC;QACD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,EAAE;gBACJ,MAAM,EAAE,CAAC,iBAAiB,IAAI,MAAM,CAAC,CAAA;gBACrC,OAAO,CAAC,CAAA;YACV,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;gBACJ,MAAM,EAAE,CAAC,iBAAiB,IAAI,SAAS,EAAE,CAAC,CAAC,CAAA;gBAC3C,MAAM,CAAC,CAAA;YACT,CAAC,CACF,CAAA;QACH,CAAC;QACD,MAAM,EAAE,CAAC,iBAAiB,IAAI,MAAM,CAAC,CAAA;QACrC,OAAO,MAAM,CAAA;IACf,CAAC,CAAC,CAAA;AACJ,CAAC"}
@@ -0,0 +1,18 @@
1
+ import type { CurrencyConfig } from '../../config';
2
+ import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from '../types';
3
+ export interface Span {
4
+ end(): void;
5
+ setError(error: unknown): void;
6
+ }
7
+ export interface Tracer {
8
+ startSpan(name: string): Span;
9
+ }
10
+ /**
11
+ * Wraps a {@link CoinModuleApi} to open a tracing span around each method invocation.
12
+ *
13
+ * The span is ended on success, or after `setError` on throw.
14
+ * The Context is forwarded unchanged to the underlying method.
15
+ * Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
16
+ */
17
+ export declare function withTracing<C extends CurrencyConfig, M extends Memo = MemoNotSupported, T extends TxData = TxDataNotSupported, Extra extends object = Record<never, never>>(api: CoinModuleApi<C, M, T> & Extra, tracer: Tracer): CoinModuleApi<C, M, T> & Extra;
18
+ //# sourceMappingURL=withTracing.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"withTracing.d.ts","sourceRoot":"","sources":["../../../src/api/wrappers/withTracing.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAGjG,MAAM,WAAW,IAAI;IACnB,GAAG,IAAI,IAAI,CAAA;IACX,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,MAAM;IACrB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,CAAC,SAAS,cAAc,EACxB,CAAC,SAAS,IAAI,GAAG,gBAAgB,EACjC,CAAC,SAAS,MAAM,GAAG,kBAAkB,EACrC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC3C,GAAG,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CA2BrF"}
@@ -0,0 +1,37 @@
1
+ // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { instrumentApi } from './instrumenter';
4
+ /**
5
+ * Wraps a {@link CoinModuleApi} to open a tracing span around each method invocation.
6
+ *
7
+ * The span is ended on success, or after `setError` on throw.
8
+ * The Context is forwarded unchanged to the underlying method.
9
+ * Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
10
+ */
11
+ export function withTracing(api, tracer) {
12
+ return instrumentApi(api, (name, fn, args) => {
13
+ const span = tracer.startSpan(name);
14
+ let result;
15
+ try {
16
+ result = fn(...args);
17
+ }
18
+ catch (e) {
19
+ span.setError(e);
20
+ span.end();
21
+ throw e;
22
+ }
23
+ if (result instanceof Promise) {
24
+ return result.then((v) => {
25
+ span.end();
26
+ return v;
27
+ }, (e) => {
28
+ span.setError(e);
29
+ span.end();
30
+ throw e;
31
+ });
32
+ }
33
+ span.end();
34
+ return result;
35
+ });
36
+ }
37
+ //# sourceMappingURL=withTracing.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"withTracing.js","sourceRoot":"","sources":["../../../src/api/wrappers/withTracing.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAItC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAW9C;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAKzB,GAAmC,EAAE,MAAc;IACnD,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,MAAe,CAAA;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAChB,IAAI,CAAC,GAAG,EAAE,CAAA;YACV,MAAM,CAAC,CAAA;QACT,CAAC;QACD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,EAAE;gBACJ,IAAI,CAAC,GAAG,EAAE,CAAA;gBACV,OAAO,CAAC,CAAA;YACV,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;gBACJ,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;gBAChB,IAAI,CAAC,GAAG,EAAE,CAAA;gBACV,MAAM,CAAC,CAAA;YACT,CAAC,CACF,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,CAAA;QACV,OAAO,MAAM,CAAA;IACf,CAAC,CAAC,CAAA;AACJ,CAAC"}
@@ -0,0 +1,44 @@
1
+ import type { CoinModuleImpl, OptionalApiKey } from '../api/impl';
2
+ import type { Memo, TxData } from '../api/types';
3
+ import type { Context, CurrencyConfig } from '../config';
4
+ /**
5
+ * What a module reports about the capabilities it does not implement, as a consumer sees it
6
+ * through `withDefaults`. Meant to be asserted whole:
7
+ *
8
+ * ```ts
9
+ * await expect(capabilityReport(createApi(), context)).resolves.toEqual({
10
+ * unsupported: ['call', 'craftRawTransaction', 'getRewards', 'getValidators', 'register'],
11
+ * inconsistent: [],
12
+ * })
13
+ * ```
14
+ *
15
+ * One expectation then covers what a module's api test used to spell out method by method:
16
+ * that each capability is absent, that reaching it raises `"<name> is not supported"`, and
17
+ * that `supports()` agrees. `toEqual` makes it exhaustive — a capability dropped or newly
18
+ * implemented changes the list, so the test notices instead of silently still passing.
19
+ *
20
+ * It reads a module written either way: a `CoinModuleImpl` that omits its capabilities, or a
21
+ * value built by spreading `notSupportedApi()`. Both are "not implemented" as far as
22
+ * `supports()` is concerned, which is what this observes.
23
+ */
24
+ export type CapabilityReport = {
25
+ /** Capabilities the module does not implement, sorted, each verified to raise its error. */
26
+ unsupported: OptionalApiKey[];
27
+ /**
28
+ * Capabilities `supports()` calls absent but which did not raise `"<name> is not
29
+ * supported"` when reached — a missing backfill, or an error naming another method.
30
+ * Expected to be empty.
31
+ */
32
+ inconsistent: OptionalApiKey[];
33
+ };
34
+ /**
35
+ * Builds a {@link CapabilityReport} for a coin module.
36
+ *
37
+ * Only the capabilities `supports()` reports absent are actually invoked — a real
38
+ * implementation is never called, so this never reaches the network.
39
+ *
40
+ * `getAccountInfo` is excluded: per ADR-045 its default is the `{ type: 'none' }` sentinel
41
+ * rather than an error, so it is not a capability in the sense the rest of this list is.
42
+ */
43
+ export declare function capabilityReport<ConfigType extends CurrencyConfig, MemoType extends Memo, TxDataType extends TxData>(impl: CoinModuleImpl<ConfigType, MemoType, TxDataType>, context: Context<ConfigType>): Promise<CapabilityReport>;
44
+ //# sourceMappingURL=capabilities.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/test-utils/capabilities.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjE,OAAO,KAAK,EAAiB,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAQxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4FAA4F;IAC5F,WAAW,EAAE,cAAc,EAAE,CAAA;IAC7B;;;;OAIG;IACH,YAAY,EAAE,cAAc,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,SAAS,cAAc,EACjC,QAAQ,SAAS,IAAI,EACrB,UAAU,SAAS,MAAM,EAEzB,IAAI,EAAE,cAAc,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,EACtD,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAgC3B"}
@@ -0,0 +1,41 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { optionalApiKeys } from '../api/impl';
4
+ import { withDefaults } from '../api/withDefaults';
5
+ /** Narrows a member reached by name to a callable without asserting its type. */
6
+ const isMethod = (value) => typeof value === 'function';
7
+ /**
8
+ * Builds a {@link CapabilityReport} for a coin module.
9
+ *
10
+ * Only the capabilities `supports()` reports absent are actually invoked — a real
11
+ * implementation is never called, so this never reaches the network.
12
+ *
13
+ * `getAccountInfo` is excluded: per ADR-045 its default is the `{ type: 'none' }` sentinel
14
+ * rather than an error, so it is not a capability in the sense the rest of this list is.
15
+ */
16
+ export async function capabilityReport(impl, context) {
17
+ const resolved = withDefaults(impl);
18
+ const asRecord = resolved;
19
+ const unsupported = [];
20
+ const inconsistent = [];
21
+ for (const name of optionalApiKeys) {
22
+ if (name === 'getAccountInfo' || resolved.supports(name))
23
+ continue;
24
+ const method = asRecord[name];
25
+ if (!isMethod(method)) {
26
+ inconsistent.push(name);
27
+ continue;
28
+ }
29
+ // The framework default throws synchronously, but a module may still carry a stub written
30
+ // as an async function, which rejects instead. Both count as raising the error.
31
+ const raised = await Promise.resolve()
32
+ .then(() => method(context))
33
+ .then(() => undefined, (error) => (error instanceof Error ? error.message : String(error)));
34
+ if (raised === `${name} is not supported`)
35
+ unsupported.push(name);
36
+ else
37
+ inconsistent.push(name);
38
+ }
39
+ return { unsupported: unsupported.sort(), inconsistent: inconsistent.sort() };
40
+ }
41
+ //# sourceMappingURL=capabilities.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/test-utils/capabilities.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAKtC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,iFAAiF;AACjF,MAAM,QAAQ,GAAG,CAAC,KAAc,EAA4C,EAAE,CAC5E,OAAO,KAAK,KAAK,UAAU,CAAA;AAiC7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAKpC,IAAsD,EACtD,OAA4B;IAE5B,MAAM,QAAQ,GAEV,YAAY,CAAC,IAAI,CAAC,CAAA;IACtB,MAAM,QAAQ,GAA4B,QAAQ,CAAA;IAElD,MAAM,WAAW,GAAqB,EAAE,CAAA;IACxC,MAAM,YAAY,GAAqB,EAAE,CAAA;IAEzC,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACnC,IAAI,IAAI,KAAK,gBAAgB,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAQ;QAElE,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC7B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACvB,SAAQ;QACV,CAAC;QAED,0FAA0F;QAC1F,gFAAgF;QAChF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE;aACnC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;aAC3B,IAAI,CACH,GAAG,EAAE,CAAC,SAAS,EACf,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC7E,CAAA;QAEH,IAAI,MAAM,KAAK,GAAG,IAAI,mBAAmB;YAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;YAC5D,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,YAAY,CAAC,IAAI,EAAE,EAAE,CAAA;AAC/E,CAAC"}
@@ -1,4 +1,5 @@
1
1
  import type { AssetInfo, Memo, MemoNotSupported, SendTransactionIntent, StakingOperation, StakingTransactionIntent, TxData, TxDataNotSupported } from '../api/index';
2
+ export * from './capabilities';
2
3
  type SendPartialBase = {
3
4
  type: string;
4
5
  } & Partial<Omit<SendTransactionIntent<MemoNotSupported, TxDataNotSupported>, 'intentType' | 'type'>>;
@@ -17,5 +18,4 @@ export declare function createStakingTransactionIntentMockData<MemoType extends
17
18
  export declare function createAssetInfoMockData(partial: {
18
19
  type: string;
19
20
  } & Partial<Omit<AssetInfo, 'type'>>): AssetInfo;
20
- export {};
21
21
  //# sourceMappingURL=helpers.d.ts.map