fix(importer)!: leave the devMode default to OneSchema

[behnam-oneschema]

Summary

0.8 replaced devMode's process.env.NODE_ENV guess with an SDK-side false (#196). Per discussion, the default should not live in the SDK at all: dev_mode is a server-side concept — it is persisted on the Embed record, folded into the embed-init dedup launch key, sent to Analytics.identify, and drives whether the embed renders diagnostics or end-user error copy — so OneSchema owns its default and the SDK only reports an explicit host choice.

 DEFAULT_PARAMS = {
-  devMode: false,
 }

-queryParams.push(`dev_mode=${this.#params.devMode}`)
+if (this.#params.devMode !== undefined) {
+  queryParams.push(`dev_mode=${this.#params.devMode}`)
+}

devMode stays boolean | undefined in the public type, so nothing changes for a host that passes it: devMode: false still sends dev_mode=false, distinguishable from unset. Unset now omits the param entirely, and the embed's urlParams.get("dev_mode") === "true" plus rubeos' cleaned[:dev_mode] || false supply the default — the same effective behavior as before for every host that did not set it, but decided in one place.

The SDK's own devMode uses (showing a failed launch's iframe instead of honoring autoClose) treat unset as off, unchanged.

Test plan

• yarn workspace @oneschema/importer test:ci — 36/36, including a new case asserting the embed URL carries no dev_mode when unset and dev_mode=true/dev_mode=false when set explicitly.
• yarn build, yarn docs:api (regenerated the core README option table), yarn fix, yarn check — clean apart from the pre-existing filefeeds-react saveSession hook warning on main.

Link to Devin session: https://app.devin.ai/sessions/0f6a86671bae4388870cb4d122431d2b
Open in Devin Desktop: https://app.devin.ai/desktop/session/0f6a86671bae4388870cb4d122431d2b?variant=devin
Requested by: @behnam-oneschema

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 11cb19af-c96e-456b-8b8d-cf2023f14f99

📥 Commits

Reviewing files that changed from the base of the PR and between 4d03cb9 and 32ff0e5.

📒 Files selected for processing (6)

• .changeset/explicit-devmode-and-legacy-removal.md
• MIGRATING-0.8.md
• packages/importer/README.md
• packages/importer/src/config.ts
• packages/importer/src/importer.ts
• packages/importer/test/importer.test.cjs

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

---

Walkthrough

The importer no longer defaults devMode to false. It omits dev_mode when unset and serializes explicit boolean values. Tests and migration documentation cover the updated behavior.

Changes

devMode behavior

Layer / File(s)	Summary
Runtime defaults and URL serialization packages/importer/src/config.ts, packages/importer/src/importer.ts, packages/importer/test/importer.test.cjs, .changeset/*	The importer removes the devMode default, sends dev_mode only when configured, and tests unset, true, and false values.
Migration and option documentation MIGRATING-0.8.md, packages/importer/README.md, packages/importer/src/config.ts	Documentation states that unset devMode delegates default selection to OneSchema and that explicit dev mode renders diagnostics in the embed.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 32ff0

The SDK now omits devMode when the host leaves it unset while preserving explicit true or false values; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Check	✅ Passed	No security concern is introduced by this PR. The change only removes the SDK default devMode: false and omits dev_mode when the value is undefined; explicit boolean values remain unchanged. The…
Title check	✅ Passed	The title uses the required Conventional Commits format and accurately describes the change to leave the devMode default to OneSchema.
Description check	✅ Passed	The description clearly explains the devMode behavior change, explicit true and false handling, tests, and documentation updates.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3 files. (3 skipped: 3 unsupported.)

Full details: Security Check

Explanation

No security concern is introduced by this PR. The change only removes the SDK default devMode: false and omits dev_mode when the value is undefined; explicit boolean values remain unchanged. The changed path adds no new user-controlled data, authentication flow, message handling, origin handling, or dependency. merged() removes undefined values, and the existing origin/source checks and postMessage target remain unchanged. Any pre-existing lack of URL encoding for other parameters is outside this PR.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devin/devmode-backend-default

---

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

[devin-ai-integration]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

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.

[github-actions]

Bundle size report

Package/file	Gzip size	Raw size	Delta vs base (gzip)
@oneschema/angular/esm2022/base-index.mjs	553 B	700 B	0 B (0.00%)
@oneschema/angular/esm2022/oneschema-angular.mjs	421 B	512 B	0 B (0.00%)
@oneschema/angular/esm2022/src/lib/oneschema.button.mjs	1,759 B	3,194 B	0 B (0.00%)
@oneschema/angular/esm2022/src/lib/oneschema.module.mjs	1,459 B	3,363 B	0 B (0.00%)
@oneschema/angular/esm2022/src/lib/oneschema.params.mjs	603 B	848 B	0 B (0.00%)
@oneschema/angular/esm2022/src/lib/oneschema.service.mjs	1,544 B	3,189 B	0 B (0.00%)
@oneschema/angular/esm2022/src/public-api.mjs	517 B	761 B	0 B (0.00%)
@oneschema/angular/fesm2022/oneschema-angular.mjs	1,551 B	5,217 B	0 B (0.00%)
@oneschema/filefeeds-react/main.js	7,857 B	35,825 B	0 B (0.00%)
@oneschema/filefeeds-react/module.js	7,730 B	35,424 B	0 B (0.00%)
@oneschema/filefeeds-react/module.mjs	7,731 B	35,425 B	0 B (0.00%)
@oneschema/filefeeds/main.js	6,694 B	29,909 B	0 B (0.00%)
@oneschema/filefeeds/module.js	6,647 B	29,774 B	0 B (0.00%)
@oneschema/filefeeds/module.mjs	6,648 B	29,775 B	0 B (0.00%)
@oneschema/filefeeds/oneschema-filefeeds-0.5.3.min.js	3,278 B	9,350 B	0 B (0.00%)
@oneschema/filefeeds/oneschema-filefeeds-0.5.latest.min.js	3,282 B	9,355 B	0 B (0.00%)
@oneschema/importer/main.js	11,869 B	59,268 B	+1 B (0.01%)
@oneschema/importer/module.js	11,809 B	58,985 B	-2 B (-0.02%)
@oneschema/importer/module.mjs	11,809 B	58,986 B	-3 B (-0.03%)
@oneschema/importer/oneschema-importer-0.7.7.min.js	5,413 B	16,635 B	-1 B (-0.02%)
@oneschema/importer/oneschema-importer-0.7.latest.min.js	5,418 B	16,640 B	0 B (0.00%)
@oneschema/react/main.js	14,857 B	69,724 B	0 B (0.00%)
@oneschema/react/module.js	14,743 B	69,120 B	-3 B (-0.02%)
@oneschema/react/module.mjs	14,744 B	69,121 B	-3 B (-0.02%)
@oneschema/vue/main.js	30,363 B	134,063 B	-4 B (-0.01%)
@oneschema/vue/module.js	30,310 B	133,932 B	-3 B (-0.01%)
@oneschema/vue/module.mjs	30,310 B	133,933 B	-4 B (-0.01%)

[devin-ai-integration]

Browser E2E against staging: devMode default left to OneSchema

Built this branch (yarn build) in a separate checkout and ran the vanilla harness (packages/importer/test, importing ../src — branch source, not the npm dist) on http://localhost:4242 against the staging embed https://embed.devschema.co, ci client, template crm_test, run-time-signed user JWT (plus a corrupted-signature variant). Five instances: devMode omitted, devMode: true, both again with a bad JWT, and a devMode: false control. A raw postMessage observer logs each embed reply before the SDK's embedInitId gating.

URL construction, verbatim — and a real import on the unset path

devMode omitted:  https://embed.devschema.co/embed-launcher?embed_client_id=60fa33a3-55af-4258-9994-647a405b64dd
devMode: true:    https://embed.devschema.co/embed-launcher?embed_client_id=60fa33a3-55af-4258-9994-647a405b64dd&dev_mode=true
devMode: false:   https://embed.devschema.co/embed-launcher?embed_client_id=60fa33a3-55af-4258-9994-647a405b64dd&dev_mode=false

No dev_mode at all when unset — in particular not dev_mode=undefined, which is what dropping DEFAULT_PARAMS.devMode without the !== undefined guard would have produced and which would still have looked "default-free" to a casual check.

The unset path completed a real import end-to-end against staging (upload → header row → map → review → Import):

A launch() RESOLVED after 252ms | sessionToken=present (36 chars) embedId=296820 | status=launched
A event "success"  type="local"  payload={"type":"local","data":{"embed_id":296820,"template_key":"crm_test",
  "workspace_id":1009655,"sheet_id":267154,"sheet_metadata":{"original_file_name":"small_contacts.csv"},"count":3,…,"error_records":[]}}
← raw reply "complete" embedInitId="mtgy3hg6-5"

⚠️ devMode: true timed out on the first attempt, passed on rerun — worth a second look

On the first pass, both devMode: true instances rejected with Timeout(5) at ~20s even though the embed had visibly rendered its importer UI with the green "Development mode" badge:

B launch() REJECTED after 20002ms | error=Timeout(5) message="OneSchema failed to respond for initialization"
D launch() REJECTED after 20001ms | error=Timeout(5)

The devMode-unset instances were fine in the same pass. Nothing in the embed launcher's host-message handling or reply posting is gated on devMode, so a raw pre-gating postMessage observer plus a devMode: false control were added and the run repeated. The reruns were clean and the ids round-tripped:

← RAW reply from B (devMode: true): messageType="init-received" embedInitId="mtgy2f99-2"
← RAW reply from B (devMode: true): messageType="init-recieved" embedInitId="mtgy2f99-2"
← RAW reply from B (devMode: true): messageType="launched"      embedInitId="mtgy2f99-2"
B launch() RESOLVED after 312ms | sessionToken=present (36 chars) embedId=296820
E launch() RESOLVED after 782ms   (dev_mode=false control — an explicit param is not itself the problem)

Not reproducible across three later attempts and not root-caused. Flagging it rather than calling this path clean.

Failure visibility: unset behaves as "dev mode off", true keeps the iframe up

Identical typed rejection on both, differing on exactly the visibility axis:

C (devMode UNSET) REJECTED after 50ms | instanceof OneSchemaLaunchFailure=true error=LaunchError(3) status=422 message="Invalid JWT: …"
C after rejection: display="none"    visibleOnScreen=false status=idle

D (devMode: true) REJECTED after 35ms | instanceof OneSchemaLaunchFailure=true error=LaunchError(3) status=422
D after rejection: display="initial" visibleOnScreen=true  status=idle

Both prompt (35–50ms, not the 20s deadline). After the successful unset import the iframe also auto-closed (display="none" status=idle), so autoClose is honored on the unset path in both the success and failure directions.

Other observations: the unset bad-JWT path emits one SDK error event (severity: "fatal") because the embed's non-dev-mode branch posts a generic error in addition to launch-error — expected, and absent under devMode: true. page-loaded, user-activity and that generic error reply arrive with no embedInitId; harmless today since none is gated. Unhandled rejections 0, console.error 0. Methodology caveat: file selection was injected over CDP because the input is in a cross-origin iframe; every later step was a real UI click.