feat: dual-publish ESM + CJS builds (#52)

## Summary

Closes #48.

The SDK has been ESM-only since extraction, which forced CJS consumers
(Node services that `require()`) to either re-implement the client or
use dynamic-import workarounds. This PR adds a CommonJS build alongside
the existing ESM output so a plain `require("@layerv/qurl")` works out
of the box.

## What changed

- **Two `tsc` passes from one source tree.** `tsconfig.json` keeps
emitting ESM (now under `dist/esm/`); a new `tsconfig.cjs.json` extends
it and emits CJS to `dist/cjs/`.
- **Per-condition `exports` map** — `import` and `require` each point at
their matching build, with `types` first inside each so
`moduleResolution: Node16` consumers resolve the correct `.d.ts`.
- **Sidecar `package.json` per dist tree.** `scripts/postbuild.mjs`
writes `{"type":"commonjs"}` into `dist/cjs/` and `{"type":"module"}`
into `dist/esm/` so Node pins each tree's module format independently of
the root `"type"` field.
- **End-to-end smoke fixtures.** `smoke/cjs.cjs` and `smoke/esm.mjs`
self-reference `@layerv/qurl` (matching how a downstream consumer
resolves it) and assert the public surface loads. CI runs both after
`npm run build`.
- **Legacy `main` / `module` / `types` fields** kept for tooling that
doesn't read `exports`.
- **README + CONTRIBUTING** updated to drop the ESM-only note and
document the dual-build layout.

## Acceptance criteria (from #48)

- [x] `require('@layerv/qurl')` works without flags or workarounds —
`smoke/cjs.cjs` proves it.
- [x] Existing ESM consumers keep working — `smoke/esm.mjs` proves it;
existing test suite (67 tests) still passes.
- [x] Both entry points come out of one build — `npm run build` runs
both tsc passes + the postbuild sidecar drop.
- [x] `exports` gains a `require` condition; types resolve from both
entry points.
- [x] CI smoke: both fixtures run on every PR.
- [x] Additive change — no breaking change to ESM consumers; Release
Please will publish as a minor.

## Heads-up for reviewers

- The `dist/` layout changes from `dist/index.js` to
`dist/{esm,cjs}/index.js`. Anyone deep-importing past the public root
(e.g. `@layerv/qurl/dist/index.js`) would break. Issue #48 notes the SDK
has zero real consumers today, so this is acceptable; the `exports`
field is the public contract going forward.
- TypeScript 6 deprecated `moduleResolution: Node10`. The CJS tsconfig
sets `ignoreDeprecations: "6.0"` to silence the warning until we
migrate; the resolution algorithm itself still works correctly for CJS
output.

## Test plan

- [x] `npm run build` — both passes succeed, sidecars land
- [x] `npm test` — 67 existing tests pass
- [x] `npm run smoke:dist` — CJS + ESM self-reference fixtures both
resolve and instantiate
- [x] `node -e 'const {QURLClient} = require("./dist/cjs");
console.log(new QURLClient({apiKey:"x"}))'` — masked-key inspect output
prints
- [x] `node --input-type=module -e '...'` ESM equivalent — same output
- [x] `npm pack --dry-run` — only `dist/` ships; `smoke/`, `scripts/`,
`tsconfig.cjs.json` correctly excluded

Author: justin-layerv

.github/workflows/ci.yml

@@ -23,6 +23,7 @@ jobs:
       - run: npm run lint
       - run: npm run format:check
       - run: npm test
+      - run: npm run smoke:dist
 
   notify:
     name: Notify

CONTRIBUTING.md

@@ -13,14 +13,48 @@ npm install
 ## Running Checks
 
 ```bash
-npm run build          # Compile TypeScript
+npm run build          # Compile TypeScript (ESM + CJS)
 npm test               # Run tests (vitest)
+npm run smoke:dist     # Verify the built ESM and CJS entry points load
 npm run format:check   # Check formatting (prettier)
 npx eslint src/        # Lint
 ```
 
 All must pass before submitting a PR.
 
+## Dual Build (ESM + CJS)
+
+The package emits two builds from one source tree:
+
+- `tsconfig.json` → `dist/esm/` (ESM, `module: Node16`)
+- `tsconfig.cjs.json` → `dist/cjs/` (CJS, `module: CommonJS`)
+
+`scripts/postbuild.mjs` drops a `package.json` sidecar into each output
+directory so Node resolves the emitted `.js` files as the right format
+regardless of the root `"type"` field. The package's `exports` field
+points each condition (`import`, `require`) at its matching build, with
+per-condition `types` so `moduleResolution: Node16` consumers get the
+right `.d.ts`.
+
+`smoke/cjs.cjs` and `smoke/esm.mjs` self-reference `@layerv/qurl` and
+exercise both entry points end-to-end; `smoke/parity.mjs` additionally
+asserts both builds export the same runtime name set. CI runs all three
+after the build. These are the load-bearing checks that the consumer-
+facing surface still loads — don't skip them when changing build
+configuration.
+
+**`npm run dev` only watches the ESM build.** Both configs share
+everything except `module`/`moduleResolution`/`outDir`, so a CJS-only
+break is unlikely, but run `npm run build` before publishing any
+build-config change to confirm both trees still compile.
+
+**Avoid module-scope mutable state** (caches, singletons, `WeakMap`
+registries). A mixed-dependency tree can load both `dist/esm/index.js`
+and `dist/cjs/index.js` as separate module instances — `instanceof`
+checks across the boundary would fail and any shared state would
+diverge. Classes and plain constants are safe; only flag state added
+at module scope is the hazard.
+
 ## API Contract Snapshot
 
 `contract/openapi.snapshot.yaml` is a hand-maintained minimal OpenAPI

README.md

@@ -16,7 +16,7 @@ AI agents need to access protected resources — APIs, databases, internal tools
 npm install @layerv/qurl
 ```
 
-> **Note:** This package is ESM-only. It requires Node.js 18+ and `"type": "module"` in your `package.json` (or use `.mjs` extensions).
+Requires Node.js 18+. Both `import { QURLClient } from '@layerv/qurl'` (ESM) and `const { QURLClient } = require('@layerv/qurl')` (CJS) work.
 
 ## Quick Start
 

package.json

@@ -3,22 +3,32 @@
   "version": "0.1.0",
   "description": "TypeScript SDK for the QURL API - secure, time-limited access links",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/postbuild.mjs",
+    "dev": "tsc -p tsconfig.json --watch",
     "test": "vitest run",
     "lint": "eslint src/",
-    "format": "prettier --write 'src/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts'",
-    "prepublishOnly": "npm run build"
+    "format": "prettier --write 'src/**/*.ts' 'smoke/**/*.{cjs,mjs}' 'scripts/**/*.mjs'",
+    "format:check": "prettier --check 'src/**/*.ts' 'smoke/**/*.{cjs,mjs}' 'scripts/**/*.mjs'",
+    "smoke:dist": "node smoke/cjs.cjs && node smoke/esm.mjs && node smoke/parity.mjs",
+    "prepublishOnly": "npm run build && npm run smoke:dist"
   },
   "keywords": [
     "qurl",

scripts/clean.mjs

@@ -0,0 +1,8 @@
+// Pre-build cleanup. Extracted from an inline `node -e` in package.json
+// to match the style of postbuild.mjs and stay robust to any future
+// Node default-module-type change.
+import { rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const dist = fileURLToPath(new URL("../dist", import.meta.url));
+rmSync(dist, { recursive: true, force: true });

scripts/postbuild.mjs

@@ -0,0 +1,14 @@
+// Pin each dist tree's module format via a sidecar package.json so a
+// future flip of the root `"type"` field can't silently mis-resolve
+// downstream consumers.
+import { writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// Resolve against this file's location rather than process.cwd() so
+// the script behaves identically whether invoked via npm scripts
+// (cwd = package root) or directly from another directory.
+const esm = fileURLToPath(new URL("../dist/esm/package.json", import.meta.url));
+const cjs = fileURLToPath(new URL("../dist/cjs/package.json", import.meta.url));
+
+writeFileSync(esm, '{"type":"module"}\n');
+writeFileSync(cjs, '{"type":"commonjs"}\n');

smoke/cjs.cjs

@@ -0,0 +1,24 @@
+// CJS consumer smoke test. Resolves the package via its `exports.require`
+// condition using a package self-reference, exactly like a downstream
+// `require("@layerv/qurl")` would. Intentionally covers only a minimal
+// happy-path surface — full-surface drift between the two builds is
+// caught by smoke/parity.mjs, and end-to-end client behavior is covered
+// by the vitest suite. Don't pad this out.
+const { QURLClient, QURLError, ValidationError, VERSION } = require("@layerv/qurl");
+
+if (typeof QURLClient !== "function") {
+  throw new Error("QURLClient is not a constructor");
+}
+if (typeof QURLError !== "function" || typeof ValidationError !== "function") {
+  throw new Error("error classes did not load");
+}
+if (typeof VERSION !== "string") {
+  throw new Error("VERSION not exported");
+}
+
+const client = new QURLClient({ apiKey: "lv_live_smoke" });
+if (typeof client.create !== "function" || typeof client.resolve !== "function") {
+  throw new Error("client methods not callable");
+}
+
+console.log("CJS smoke ok");

smoke/esm.mjs

@@ -0,0 +1,21 @@
+// ESM consumer smoke test. Mirror of cjs.cjs through `exports.import`
+// via a package self-reference. Same scope as cjs.cjs — minimal happy-
+// path; full-surface drift is caught by smoke/parity.mjs.
+import { QURLClient, QURLError, ValidationError, VERSION } from "@layerv/qurl";
+
+if (typeof QURLClient !== "function") {
+  throw new Error("QURLClient is not a constructor");
+}
+if (typeof QURLError !== "function" || typeof ValidationError !== "function") {
+  throw new Error("error classes did not load");
+}
+if (typeof VERSION !== "string") {
+  throw new Error("VERSION not exported");
+}
+
+const client = new QURLClient({ apiKey: "lv_live_smoke" });
+if (typeof client.create !== "function" || typeof client.resolve !== "function") {
+  throw new Error("client methods not callable");
+}
+
+console.log("ESM smoke ok");

smoke/parity.mjs

@@ -0,0 +1,34 @@
+// Structural drift detector: a runtime name added to only one of the two
+// builds (e.g. a future conditional export that ships in ESM but not CJS)
+// would land in prod silently without this check — the per-build cjs.cjs
+// and esm.mjs smokes can't see the other side.
+import { createRequire } from "node:module";
+import assert from "node:assert/strict";
+
+const require = createRequire(import.meta.url);
+const cjs = require("@layerv/qurl");
+const esm = await import("@layerv/qurl");
+
+// Raw Object.keys on both — no filtering. A `default` export landing in
+// only one build is exactly the ESM-only drift this check exists to
+// catch; filtering it would silently pass the asymmetric case. The
+// Node-synthesized `default` for CJS-interop imports doesn't apply
+// here since both sides are resolved through their own `exports`
+// condition, not via cross-format interop.
+//
+// TS's CJS emit marks the namespace with `__esModule` via
+// `Object.defineProperty(exports, "__esModule", { value: true })`,
+// which is non-enumerable by default and so is correctly excluded
+// from Object.keys. A future TS emit change that makes it enumerable
+// would surface as a spurious "cjs has __esModule, esm doesn't" diff
+// here — that's the correct outcome (loud signal to investigate).
+const cjsKeys = Object.keys(cjs).sort();
+const esmKeys = Object.keys(esm).sort();
+
+assert.deepStrictEqual(
+  cjsKeys,
+  esmKeys,
+  `ESM/CJS export drift:\n  cjs: ${cjsKeys.join(", ")}\n  esm: ${esmKeys.join(", ")}`,
+);
+
+console.log(`Parity ok (${cjsKeys.length} names)`);

tsconfig.cjs.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    // TODO: TS 7 will drop `Node10`. Migrate to `module: "Node16"` + a
+    // source-side CJS sidecar (or matching `.cts` entry) before then.
+    "moduleResolution": "Node10",
+    "outDir": "./dist/cjs",
+    "ignoreDeprecations": "6.0",
+    // The ESM tree already emits declaration + source maps from the same
+    // `src/` tree; emitting them again into `dist/cjs/` doubles tarball
+    // size for no additional signal. The ESM maps themselves ship but
+    // reference `src/` which `files: ["dist/"]` excludes (see #53);
+    // fixing that is a separate decision, and double-shipping broken
+    // maps on the CJS side wouldn't help either way.
+    "declarationMap": false,
+    "sourceMap": false
+  }
+}