Issue 262 publint audit by Sukuna0007Abhi · Pull Request #417 · caravan-bitcoin/caravan

Sukuna0007Abhi · 2025-12-03T19:06:50Z

Fixes #262

Issue proof:

This PR addresses all publint warnings and suggestions for the published packages by implementing proper module type declarations and export conditions.

I don't added any documentation related to it...

Changes Made

All packages (@caravan/bitcoin, @caravan/psbt, @caravan/wallets, @caravan/multisig):

Added "type": "commonjs" field for proper Node.js module detection
Updated exports field with separate type conditions for ESM and CommonJS
Added .d.mts generation for proper ESM TypeScript support
Included .d.mts files in the published package files array
Updated build scripts to automatically generate .d.mts from .d.ts
Fixed repository URLs to use proper git+https:// format with directory field for monorepo packages

@caravan/bip32:

Since this package uses "type": "module", implemented .d.cts generation for CommonJS types
Updated exports to use .d.cts for require condition and .d.mts for import condition
Modified generation script to use ESM syntax (import/export) instead of CommonJS

@caravan/clients:

Added missing exports field (previously only had module field which Node.js ignores)
Configured proper ESM/CommonJS export conditions with corresponding type declarations

Testing

All packages now pass publint validation with zero warnings or errors. Verified locally using:

npx publint packages/caravan-bitcoin
npx publint packages/caravan-psbt
npx publint packages/caravan-wallets
npx publint packages/bip32
npx publint packages/multisig
npx publint packages/caravan-clients

Proofs:

Breaking Changes

The addition of exports field to @caravan/clients is technically a breaking change as it changes how the package can be imported, though it enables proper ESM support that was previously not working correctly.

All other changes are backwards compatible improvements to package metadata and type declarations.

Ready for review @bucko13 @Legend101Zz

Fixes caravan-bitcoin#262 Conducted comprehensive publint audit and implemented all fixes: - Added type: commonjs field to 5 packages for proper Node.js module detection - Fixed repository URLs to proper git+https format with directory field - Added .d.mts generation scripts for proper ESM type support Packages updated: @caravan/bitcoin, @caravan/psbt, @caravan/wallets, @caravan/clients, @caravan/multisig, @caravan/bip32 All publint suggestions and warnings now resolved. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

bip32 package has type: module so the script needs ESM imports Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

Since bip32 has type: module, .d.ts files are treated as ESM. For proper CommonJS type support, we need .d.cts extension. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

pkg.module is not read by Node.js without pkg.exports defined. Added proper exports field with ESM/CJS conditions and .d.mts types. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

changeset-bot · 2025-12-03T19:06:54Z

⚠️ No Changeset found

Latest commit: be9b369

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2025-12-03T19:06:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
caravan-coordinator	Ready	Preview, Comment	Feb 17, 2026 10:35pm

bucko13 · 2025-12-03T20:05:33Z

packages/bip32/scripts/generate-mts-dts.js

i don't think this is right. we should use the build system (tsup) to generate different module type files.

Ok, understood, you're right, I converted it as you said...,pls review

Sorry, i think you misunderstood the comment. I wasn't saying to use tsup to run the copy and move. Tsup is a build system that produces the modules that are needed. you can configure to output the file types you want. If you simply copy/rename you can end up with errors.

Ok, sir I got it, I took other approaches, pls reviewe in your free time

- Replace manual scripts with tsup onSuccess hooks - Add onSuccess hooks to all tsup.config files to generate .d.mts and .d.cts - Remove manual generate-mts-dts.js scripts from all packages - Clean up package.json build commands This addresses the maintainer feedback to use the build system (tsup) instead of manual scripts for generating module type declaration files. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

Sukuna0007Abhi · 2025-12-05T19:48:21Z

Ready for review @bucko13 @Legend101Zz

Legend101Zz · 2025-12-19T01:51:04Z

@Sukuna0007Abhi thanks for the PR and sorry for the delay in reviews ... I'll try to find some time today to take a look at this ...

Legend101Zz

Thanks for the PR ... a couple of requests from my end , mainly regarding the opying index.d.ts → index.d.mts and index.d.cts stuff

Legend101Zz · 2025-12-19T20:00:12Z

packages/bip32/tsup.config.js

+    const dctsFile = join(distDir, "index.d.cts");
+
+    if (existsSync(dtsFile)) {
+      copyFileSync(dtsFile, dmtsFile);


@Sukuna0007Abhi this is what @bucko13 was pointing out earlier while the package.json changes you did are indeed correct, the file copying approach in tsup.config.js is problematic ( even though if it would be working )

Simply copying index.d.ts → index.d.mts and index.d.cts assumes all three files can have identical syntax. This isn't true:

Different module systems require different TypeScript syntax:

// ESM declarations (.d.mts) must use: export default class BIP32 { } // CommonJS declarations (.d.cts) must use: declare class BIP32 { } export = BIP32;

If you copy ESM syntax into a .d.cts file, TypeScript will throw errors for CommonJS users who use require().

As to Why This Might Seem to Work Initially

If your exports only use simple patterns like export function foo(), the syntax is similar enough in both module systems that copying might work. But this breaks as soon as you use:

Default exports (export default)

Re-exports (export * from)

More complex module patterns

So I guess the correct solution would be to :

Let tsup generate the declaration files for each module format:

// tsup.config.js export default defineConfig({ entry: ['src/index.ts'], format: ['esm', 'cjs'], // Generate both formats dts: true, // tsup will create .d.ts, .d.mts, and .d.cts esbuildPlugins: [polyfillNode({ polyfills: { crypto: false } })], // Remove the onSuccess file copying code });

Legend101Zz · 2025-12-19T20:02:04Z

packages/caravan-bitcoin/tsup.config.ts

    provideSelf(),
    provideNavigator(),
  ],
+  onSuccess: async () => {


again remove the file copying and let tsup generate both

Legend101Zz · 2025-12-19T20:02:32Z

packages/caravan-clients/tsup.config.ts

+    const dtsFile = join(distDir, "index.d.ts");
+    const dmtsFile = join(distDir, "index.d.mts");
+
+    if (existsSync(dtsFile)) {


Legend101Zz · 2025-12-19T20:04:12Z

packages/multisig/tsup.config.js

  esbuildPlugins: [nodeModulesPolyfillPlugin()],
+  onSuccess: async () => {
+    const distDir = join(process.cwd(), "dist");
+    const dtsFile = join(distDir, "index.d.ts");


packages/caravan-bitcoin/package.json

Legend101Zz · 2025-12-19T20:08:53Z

packages/caravan-psbt/tsup.config.ts

    provideNavigator(),
  ],
+  onSuccess: async () => {
+    const distDir = join(process.cwd(), "dist");


Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

…310@gmail.com>

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

Simplified comments and improved regex to extract declaration name properly. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

Sukuna0007Abhi · 2026-01-25T17:45:45Z

Pls check @bucko13

Legend101Zz · 2026-02-10T12:13:02Z

@Sukuna0007Abhi we have marked the PR ready for review , Buck will surely find time and duely do the final review , you can take up other issues if you'd like in the meanwhile , thanks :)

Sukuna0007Abhi · 2026-02-10T12:33:47Z

@Sukuna0007Abhi we have marked the PR ready for review , Buck will surely find time and duely do the final review , you can take up other issues if you'd like in the meanwhile , thanks :)

Yeah sure 👍 @Legend101Zz I am already working on PR #458 which you reviewed already and I am doing the changes you told

bucko13 · 2026-02-10T14:44:33Z

I'm still very nervous and skeptical of the need to write custom scripts that manually change the files that ultimately get used in bundles. I'd rather take the warnings we have but know work and are widely supported than have to effectively write and maintain our own bundler. I haven't caught up on the comments thus far, but I dont understand how the correct exports aren't supported from a popular and well supported bundler used by hundreds of thousands of other libraries

Sukuna0007Abhi · 2026-02-10T14:51:43Z

I'm still very nervous and skeptical of the need to write custom scripts that manually change the files that ultimately get used in bundles. I'd rather take the warnings we have but know work and are widely supported than have to effectively write and maintain our own bundler. I haven't caught up on the comments thus far, but I dont understand how the correct exports aren't supported from a popular and well supported bundler used by hundreds of thousands of other libraries

Actually it's only for @caravan/bip32, it's needs to use custom scripts because it:
It generates both .d.mts (ESM) and .d.cts(CommonJs) declaration files

Performs a special transformation something like on .d.cts: converts export default syntax to export = for proper CommonJs typing

And this transformation isn't currently handled by tsup's experimentalDts

So, that's why this custom scripts will help for this dual module setup..

If you insist on it, then I will just ignore & revert the bip32 part only, then there will be no custom scripts

What you say @bucko13

bucko13 · 2026-02-10T14:56:14Z

So if there were no commonjs export for BIP32 then the custom transform wouldn't be necessary? It seems like the ecosystem is moving away from needing commonjs so if we set the right minimum engine in the package.json and just avoid that entirely than that would be fine too.

Sukuna0007Abhi · 2026-02-10T15:18:11Z

So if there were no commonjs export for BIP32 then the custom transform wouldn't be necessary? It seems like the ecosystem is moving away from needing commonjs so if we set the right minimum engine in the package.json and just avoid that entirely than that would be fine too.

Sorry my net got bumped,

Yeah, fully correct , it's actually perfect, we can do this

Sukuna0007Abhi · 2026-02-10T15:20:22Z

So if there were no commonjs export for BIP32 then the custom transform wouldn't be necessary? It seems like the ecosystem is moving away from needing commonjs so if we set the right minimum engine in the package.json and just avoid that entirely than that would be fine too.

Sorry my net got bumped,

Yeah, fully correct , it's actually perfect, we can do this

So, should I revert the changes I did for bip32 & make sure package.json has the right minimum node version @bucko13

Sukuna0007Abhi · 2026-02-10T15:27:48Z

But, I have a concern now, caravan-psbt has "type":"commonjs" and depends on @caravan/bip32

I will test it, 1st that, caravan-psbt build correctly when importing ESM-only bip32?

If psbt uses import statements (not require), then the bundler should handle it fine even though psbt has "type":"commonjs"

Sukuna0007Abhi · 2026-02-10T15:33:23Z

But, I think, it will be safe to drop commonjs for bip32

Cause, I'm seeing this:

Caravan-psbt (CommonJs package) actually imports bip32 using this:

import { combineBip32Paths } from "@caravan/bip32";

It's not using require(), so I guess I will drop as you suggested

…cript Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

- Add explicit outExtension in tsup.config for consistency - Add format flag in build script to match other packages - Keep ESM-only structure as intended Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

bucko13 · 2026-02-10T16:36:50Z

So, should I revert the changes I did for bip32 & make sure package.json has the right minimum node version

Yes @Sukuna0007Abhi I think that would be great. thank you!

Sukuna0007Abhi · 2026-02-10T17:10:35Z

Hi @bucko13 I fixed up and revert all the bip32 commonJs part and also I faced a issue when building caravan-wallets, saw it's a pre-existing TypeScript issue, with the TrezorConnect import that shows up with isolatedModule enables, so I fixed that up

by

type TrezorConnect

Now as I already checked all other packages perfectly fine build and shows All Good...

Sukuna0007Abhi · 2026-02-10T17:10:47Z

So, should I revert the changes I did for bip32 & make sure package.json has the right minimum node version

Yes @Sukuna0007Abhi I think that would be great. thank you!

Pls review

bucko13

Left some comments and questions. I'm wondering if we should be moving to just the modern module type for all packages. Some other questions about types as well to see if we can avoid any especially in newer packages that should be well typed.

Thanks for bearing with me on this!

bucko13 · 2026-02-10T23:12:49Z

packages/bip32/package.json

  "types": "./dist/index.d.ts",
  "files": [
    "./dist/index.js",
-    "./dist/index.cjs",


this might require a major version bump. if any other systems used this as a commonjs import then this would break it.

bucko13 · 2026-02-10T23:13:13Z

packages/caravan-bitcoin/tsup.config.ts

+  dts: {
+    resolve: true,
+  },
+  clean: true,


what does this option do?

bucko13 · 2026-02-10T23:13:48Z

packages/caravan-clients/package.json

  "name": "@caravan/clients",
  "version": "1.0.2",
  "description": "A package for querying different bitcoin blockchain backends",
+  "type": "commonjs",


would things break if we did this as a module export rather than a commonjs?

bucko13 · 2026-02-10T23:15:00Z

packages/caravan-psbt/src/psbtv2/functions.ts

-  const br = new BufferReader(buf.slice(PSBT_MAGIC_BYTES.length));
+  // BufferReader expects Buffer at runtime, but TypeScript dts generation is strict
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const br = new BufferReader(buf.slice(PSBT_MAGIC_BYTES.length) as any);


@Shadouts any thoughts on this? did you ever run into any type issues when building this out?

bucko13 · 2026-02-10T23:15:34Z

packages/caravan-psbt/src/psbtv2/psbtv2.ts

   */
  private handleSighashType(sig: Buffer) {
-    const br = new BufferReader(sig.slice(-1));
+    const br = new BufferReader(sig.slice(-1) as any);


why was this necessary? does buffer reader not play nice with a buffer as an input?

bucko13 · 2026-02-10T23:16:38Z

packages/caravan-psbt/package.json

  "name": "@caravan/psbt",
  "version": "2.0.7",
  "description": "typescript library for working with PSBTs",
+  "type": "commonjs",


same here. wondering if this could be module. @Shadouts

bucko13 · 2026-02-10T23:19:25Z

packages/transactions/package.json

    "lint": "eslint src",
-    "lint:fix": "eslint --fix src"
+    "lint:fix": "eslint --fix src",
+    "postbuild": "node -e \"const fs=require('fs');fs.copyFileSync('dist/index.d.ts','dist/index.d.mts');\""


this shouldn't be necessary

bucko13 · 2026-02-10T23:19:54Z

packages/transactions/src/transactionAnalyzer.ts

    return this._rawTx.ins.map((input) => {
      const template = new BtcTxInputTemplate({
-        txid: Buffer.from(input.hash).reverse().toString("hex"), // reversed (big-endian) format
+        txid: (Buffer.from(input.hash as any).reverse() as any).toString("hex"), // reversed (big-endian) format


@Legend101Zz what do you think, can we avoid the any's here? curious why they'd be necessary.

Sukuna0007Abhi added 4 commits December 3, 2025 14:06

fix: use ESM syntax in bip32 generate-mts-dts script

897de99

bip32 package has type: module so the script needs ESM imports Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

fix: generate .d.cts for bip32 CommonJS types

36a48f4

Since bip32 has type: module, .d.ts files are treated as ESM. For proper CommonJS type support, we need .d.cts extension. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

fix: add exports field to caravan-clients package

434e10a

pkg.module is not read by Node.js without pkg.exports defined. Added proper exports field with ESM/CJS conditions and .d.mts types. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot deployed to Preview December 3, 2025 19:09 View deployment

bucko13 reviewed Dec 3, 2025

View reviewed changes

vercel bot deployed to Preview December 5, 2025 18:59 View deployment

Sukuna0007Abhi requested a review from bucko13 December 5, 2025 19:41

Legend101Zz suggested changes Dec 19, 2025

View reviewed changes

build: rely on tsup for dual outputs

8fc26dc

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot deployed to Preview December 20, 2025 15:24 View deployment

chore: emit bip32 per-format dts

2239b42

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot had a problem deploying to Preview December 20, 2025 16:15 Failure

fix: bip 32 emit per-format dts Signed-off-by:Sukuna0007Abhi <appsonl…

dfeac5c

…310@gmail.com>

vercel bot had a problem deploying to Preview December 20, 2025 17:24 Failure

fix: use stable dts for bip32

d420eb9

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot deployed to Preview December 20, 2025 19:01 View deployment

feat: emit dual dts for bip32

41bbd17

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot had a problem deploying to Preview December 20, 2025 19:17 Failure

chore: fix bip32 dts emit hook import

03c7936

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot had a problem deploying to Preview December 20, 2025 19:21 Failure

chore: build bip32 before pack

8f4c93b

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot had a problem deploying to Preview December 20, 2025 19:26 Failure

fix: point bip32 types to generated d.ts

df23f5c

Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot had a problem deploying to Preview December 20, 2025 19:36 Failure

Merge branch 'main' into issue-262-publint-audit

3f24f63

vercel bot deployed to Preview January 25, 2026 17:40 View deployment

refactor: improve default export regex in bip32 dts script

8c77a14

Simplified comments and improved regex to extract declaration name properly. Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot deployed to Preview January 25, 2026 17:46 View deployment

Merge branch 'main' into issue-262-publint-audit

cc149ce

vercel bot deployed to Preview February 6, 2026 19:32 View deployment

refactor: make bip32 ESM-only, remove CommonJS and custom transform s…

ba47cfc

…cript Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot deployed to Preview February 10, 2026 15:47 View deployment

fix: align bip32 config with other packages pattern

cfcabb1

- Add explicit outExtension in tsup.config for consistency - Add format flag in build script to match other packages - Keep ESM-only structure as intended Signed-off-by: Sukuna0007Abhi <appsonly310@gmail.com>

vercel bot deployed to Preview February 10, 2026 16:19 View deployment

fix: use .d.ts for ESM-only bip32, fix trezor type import

67c7a43

vercel bot deployed to Preview February 10, 2026 16:59 View deployment

fix: prettier formatting in HermitSignatureImporter

5984dc0

vercel bot deployed to Preview February 10, 2026 18:49 View deployment

bucko13 requested changes Feb 10, 2026

View reviewed changes

Merge branch 'main' into issue-262-publint-audit

be9b369

vercel bot deployed to Preview February 17, 2026 22:35 View deployment

Conversation

Sukuna0007Abhi commented Dec 3, 2025

Changes Made

Testing

Proofs:

Breaking Changes

Uh oh!

changeset-bot bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

vercel bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi commented Dec 5, 2025

Uh oh!

Legend101Zz commented Dec 19, 2025

Uh oh!

Legend101Zz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi commented Jan 25, 2026

Uh oh!

Legend101Zz commented Feb 10, 2026

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bucko13 commented Feb 10, 2026

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026

Uh oh!

bucko13 commented Feb 10, 2026

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026

Uh oh!

bucko13 commented Feb 10, 2026

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026

Uh oh!

Sukuna0007Abhi commented Feb 10, 2026

Uh oh!

bucko13 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

changeset-bot bot commented Dec 3, 2025 •

edited

Loading

vercel bot commented Dec 3, 2025 •

edited

Loading

Sukuna0007Abhi Dec 5, 2025 •

edited

Loading

Sukuna0007Abhi commented Feb 10, 2026 •

edited

Loading

Sukuna0007Abhi commented Feb 10, 2026 •

edited

Loading