feat(sdk): add automatic entropy generation for document creation

[thephez]

Issue being fixed or feature implemented

The evo-sdk's documents.create() method required manual entropy generation, causing poor developer experience with cryptic error messages ("Cannot read properties of undefined (reading 'length')") and forcing developers to write boilerplate code for every document creation.

What was done?

This PR adds automatic entropy generation to the documents.create() method in js-evo-sdk, making the API simpler and more consistent with other SDK methods like dpns.registerName().

Key changes:

• Made entropyHex parameter optional in documents.create()
• Added generateEntropy() utility function supporting both Node.js and browser environments
• Auto-generates cryptographically secure 32-byte entropy when not provided
• Maintains full backward compatibility - existing code with manual entropy still works
• Added comprehensive unit tests for entropy generation

How Has This Been Tested?

• Added new unit tests in tests/unit/facades/documents.spec.mjs to verify auto-generation behavior
• Added new test file tests/unit/util.spec.mjs with comprehensive tests for generateEntropy()
• All existing tests pass (105 tests passing)
• Built package successfully with yarn build

Breaking Changes

None - this change is fully backward compatible. The entropyHex parameter is now optional but still accepts values when provided.

Checklist:

• [x] I have performed a self-review of my own code
• [x] I have commented my code, particularly in hard-to-understand areas
• [x] I have added or updated relevant unit/integration/functional/e2e tests
• [x] I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• [x] I have made corresponding changes to the documentation if needed

For repository code-owners and collaborators only

• [ ] I have assigned this pull request to a milestone

Summary by CodeRabbit

• New Features

  • Entropy for document creation is now optional and will be auto-generated when omitted.
  • Added a cross-environment entropy generation utility that produces secure 32-byte entropy (works in Node and browsers, with fallback behavior).

• Tests

  • Added tests validating entropy generation format, uniqueness, byte-length, and distribution properties.
  • Updated document creation tests to verify auto-generation and that explicit entropy is forwarded unchanged.

[coderabbitai[bot]]

Walkthrough

create() in DocumentsFacade now accepts an optional entropyHex and auto-generates a 64‑char hex entropy when omitted. A new generateEntropy() util was added to produce 32 bytes (64 hex chars) of cryptographically secure entropy. Tests updated/added to cover forwarding and generation behavior.

Changes

Cohort / File(s)	Summary
Entropy Utility packages/js-evo-sdk/src/util.ts	Added generateEntropy(): string producing 32 bytes (64 hex chars) of cryptographically secure entropy with Node/Web Crypto detection and an error when no secure source is available.
Documents Facade packages/js-evo-sdk/src/documents/facade.ts	Made entropyHex optional in create() signature, imported generateEntropy, compute entropyHex = args.entropyHex ?? generateEntropy() before calling documentCreate, and pass it through.
Facade Tests packages/js-evo-sdk/tests/unit/facades/documents.spec.mjs	Updated test to assert provided entropy is forwarded; added test verifying auto-generation when entropyHex is omitted and that a 64‑char hex string is forwarded.
Utility Tests packages/js-evo-sdk/tests/unit/util.spec.mjs	New tests for generateEntropy() (64-char length, hex format, distinct outputs, decodes to 32 bytes, sampling checks) and tests for asJsonString() behavior.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant DocumentsFacade
    participant generateEntropy as EntropyUtil
    participant wasmSdk as DocumentCreate

    Caller->>DocumentsFacade: create(args {..., entropyHex?})
    alt entropyHex provided
        DocumentsFacade->>wasmSdk: documentCreate({... entropyHex ...})
    else entropyHex missing
        DocumentsFacade->>EntropyUtil: generateEntropy()
        EntropyUtil-->>DocumentsFacade: entropyHex (64‑char hex)
        DocumentsFacade->>wasmSdk: documentCreate({... entropyHex ...})
    end
    wasmSdk-->>Caller: Promise result

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–30 minutes

• Review focus:
  • Correctness and environment coverage of generateEntropy() (Node vs browser detection and error path).
  • Ensure entropyHex format and length meet documentCreate expectations.
  • Tests that assert randomness/distribution may be flaky — validate sampling approach and thresholds.

"I nibble at bytes in moonlit code,
Sixty‑four hops of hex in my tote,
A fresh seed sprung from rabbit's paw,
Documents waltz with entropy raw. 🐇"

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "feat(sdk): add automatic entropy generation for document creation" accurately reflects the primary change in this changeset. The PR introduces a new generateEntropy() utility function and modifies documents.create() to auto-generate entropy when the entropyHex parameter is omitted, which is precisely what the title communicates. The title is concise, uses standard conventional commit formatting, avoids vague terminology, and provides sufficient specificity that a developer reviewing the project history would understand the core purpose of the change.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch wasm-sdk-entropy-util

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[thephez]

@coderabbitai full review

[coderabbitai[bot]]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai[bot]]

✅ Actions performed

Full review triggered.

[lklimek]

Please rebase to 2.2-dev

[thephez]

@lklimek rebased and passing tests