Skip to content

docs(sdk): add TSDoc to the remaining public exports - #10

Merged
Miracle656 merged 1 commit into
Divinity-Labs:mainfrom
dxfareed:docs/sdk-tsdoc-6
Sep 6, 2026
Merged

Miracle656 merged 1 commit into
Divinity-Labs:mainfrom
dxfareed:docs/sdk-tsdoc-6

Conversation

@dxfareed

@dxfareed dxfareed commented Sep 5, 2026 •

Copy link
Copy Markdown

Closes #6

What changed: Added TSDoc to the 38 exported symbols reachable from sdk/src/index.ts that had none, taking the public surface from 112/150 documented to 150/150. Comments only, no runtime, type or export-surface changes.

Why: Editor tooltips were empty across most of the integration surface. bulkPayout had no doc comments at all; claimableBalance, network and feePayer were partly covered.

Where the behaviour isn't inferable from the signature, the comment says so rather than restating the types:

  • parseCSV reports ValidationError.row as a CSV line number, not an index into the returned rows (which omits rejected rows).
  • executePayout records a failed batch in failedRows and continues, so it does not reject on a batch failure.
  • buildClaimLink hardcodes the hosted wallet host, so self-hosted deployments need to build their own link.
  • FeePayerMode: 'legacy' derives from the credential ID, which is not a secret; cross-linked to the existing warning on deriveFeePayerKeypair.
  • signMessage's VEIL_SIGNED_MESSAGE_V1 domain prefix is what prevents the signature being replayed as a Soroban auth approval.

How tested:

  • npm run build in sdk/ green, and the comments are present in the emitted dist/*.d.ts, which is what actually reaches consumers.
  • npm test in sdk/ green: 24 suites, 273 tests. api-surface.test.ts passing is the guard that the export surface is unchanged.
  • npm run size byte-identical to main (228.21 kB / 214.85 kB, limits 230 / 225). Checked because main sits ~1.8 kB under its limit; comments strip in minification.
  • Diff is 321 insertions / 0 deletions, and every added line is a comment. No reformatting, no lockfile.

Not tested: nothing on a device. This change cannot reach a device.

Notes:

Two things I hit while working, both left out of this diff deliberately:

  1. scripts/flatten-dist.js is not idempotent. It renameSyncs dist/src/* up into dist/, which throws ENOTEMPTY when the target already exists, so a second npm run build over an existing dist/ fails and npm run size (which builds) fails with it. Workaround is rm -rf dist first. Happy to open a separate issue or a one-line fs.rmSync(distDir, { recursive: true, force: true }) PR if you want it.

  2. sdk/src/vanilla.ts is a separate entry point rather than something index.ts re-exports, so I read it as outside this issue's stated key files and left it alone. Both of its exports (InvisibleWallet, createInvisibleWallet) are undocumented. Say the word and I'll fold it in here or do it as a follow-up.

Also worth a second look: sdk/ builds clean only after npm ci there. On a stale node_modules the Vue/Svelte/Solid adapters fail to resolve their optional peers. Pre-existing on main, unrelated to this change, just noting it in case CI ever caches that directory.

@dxfareed
dxfareed requested a review from Miracle656 as a code owner September 5, 2026 17:27
38 of the 150 named exports reachable from sdk/src/index.ts had no doc
comment, so editor tooltips were empty on most of the integration surface.
bulkPayout had none at all; claimableBalance, network and feePayer were
partly covered.

Documents params, returns and the behaviour a caller cannot infer from the
signature: parseCSV row numbers are CSV lines rather than indices into the
returned rows, executePayout records a failed batch and continues instead of
rejecting, buildClaimLink hardcodes the hosted wallet host, and FeePayerMode
'legacy' derives from the credential ID, which is not a secret.

Comments only. No runtime, type or export-surface changes.
@Miracle656
Miracle656 merged commit 42e0025 into Divinity-Labs:main Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add TSDoc to the SDK public exports

2 participants