Repository navigation
feat(importer)!: drop the deprecated launch surface and document the 0.8 migration #196
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
12da88e
feat(importer)!: drop the deprecated launch surface and default devMo…
behnam-oneschema 265795a
fix(codemod): only rewrite call sites the transform can attribute to …
behnam-oneschema b05431f
docs(codemod): point the transform's own usage note at the tagged che…
behnam-oneschema ab3af7f
fix(codemod): keep unrelated success handlers and valueless parentId …
behnam-oneschema File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| --- | ||
| "@oneschema/importer": major | ||
| "@oneschema/react": major | ||
| "@oneschema/vue": major | ||
| "@oneschema/angular": major | ||
| --- | ||
|
|
||
| Remove the deprecated launch surface and make `devMode` explicit | ||
|
|
||
| `devMode` now defaults to `false` for every host. It used to default to `process.env.NODE_ENV !== "production"`, which reads a Node global that a browser bundle either inlines or leaves undefined, so whether the iframe stayed visible after a failed launch depended on the bundler rather than on the application. Wire it to your own build condition — `devMode={import.meta.env.DEV}` or whatever your bundler exposes — to keep the old behavior. | ||
|
|
||
| `parentId` is gone; pass the container element as `parent`. An id was resolved once, at construction, so it silently fell back to `document.body` whenever the container had not mounted yet. | ||
|
|
||
| The `launched` event's payload is now `OneSchemaLaunchEvent`, a union of `OneSchemaLaunchSucceeded` and `OneSchemaLaunchFailed` discriminated on `success`, replacing `OneSchemaLaunchStatus`. Narrow on `success` before reading a branch's fields; the failure branch carries the same detail as the `OneSchemaLaunchFailure` that `launch()` rejects with. The internals `_hasAttemptedLaunch`, `_launch`, `_initWithRetry` and `_resetSession` are gone — `importer.status` and the promise `launch()` returns cover what they were reached for. | ||
|
|
||
| [MIGRATING-0.8.md](https://github.com/oneschema/sdk/blob/main/MIGRATING-0.8.md) walks through the whole 0.7.7 → 0.8 hop, with a codemod for the mechanical parts. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,244 @@ | ||
| # Migrating to 0.8 | ||
|
|
||
| `0.8` is one hop from `0.7.7`. It carries every breaking change we intend to make in this cycle, so a host migrates once: nothing removed here is kept as a shim, and nothing is deprecated first and removed later. | ||
|
|
||
| The theme is that the SDK now tells you what actually happened. `launch()` resolves when the import session is running and rejects, with a typed error, as soon as a failure is knowable; the `success` payload says how the data was delivered; your `success` and `cancel` handlers are awaited before the importer cleans up; and the wrappers can own the importer's visibility so your application does not have to. | ||
|
|
||
| `@oneschema/filefeeds` and `@oneschema/filefeeds-react` are legacy, frozen at `0.5.3`, and unaffected by any of this. | ||
|
|
||
| Run the codemod first — it does the mechanical renames — then work through the sections below for the call sites TypeScript flags. See [Codemod](#codemod) at the end. | ||
|
|
||
| ## At a glance | ||
|
|
||
| | `0.7.7` | `0.8` | | ||
| | ------------------------------------------------- | -------------------------------------------------------------------------------- | | ||
| | `const { success } = importer.launch()` | `await importer.launch()`, rejecting with `OneSchemaLaunchFailure` | | ||
| | `onSuccess: (data) => …`, `data` untyped | `onSuccess: (result) => …`, narrow on `result.type` before reading `result.data` | | ||
| | an `async` handler ran unawaited | `success` and `cancel` are awaited, bounded by `handlerTimeoutMs` | | ||
| | a blocked iframe reported a `fatal` `error` event | `launch()` rejects with `OneSchemaLaunchError.Timeout` after `initTimeoutMs` | | ||
| | `parentId: "container"` | `parent: document.getElementById("container") ?? undefined` | | ||
| | `document.getElementById("_oneschema-iframe")` | `importer.iframe` | | ||
| | `importer._hasAttemptedLaunch` | `importer.status` | | ||
| | `devMode` defaulted from `process.env.NODE_ENV` | `devMode` defaults to `false`; pass it explicitly | | ||
| | React `isOpen` required | `isOpen` optional; omit it and launch through the component's `ref` | | ||
|
|
||
| ## Core importer | ||
|
|
||
| ### `launch()` and `launchSession()` return a promise | ||
|
|
||
| They used to return `{ success }` synchronously, where `success: true` meant "the init message was queued" — a rejected JWT or a blocked iframe still looked like a successful launch until an event arrived later. They now return a promise that resolves with `OneSchemaLaunchInfo` (`embedInitId`, plus `sessionToken` and `embedId` once the embed reports them) when the session is actually running. | ||
|
|
||
| ```javascript | ||
| // 0.7.7 | ||
| const { success } = importer.launch() | ||
| if (!success) { | ||
| showError() | ||
| } | ||
|
|
||
| // 0.8 | ||
| try { | ||
| const { sessionToken } = await importer.launch() | ||
| } catch (failure) { | ||
| showError(failure.message) | ||
| } | ||
| ``` | ||
|
|
||
| Failures reject with `OneSchemaLaunchFailure`, an `Error` subclass carrying `error` (a `OneSchemaLaunchError`), `embedInitId`, and `status`/`data`/`cause` when the failure came from an API call or an embed payload: | ||
|
|
||
| ```javascript | ||
| import { OneSchemaLaunchError } from "@oneschema/importer" | ||
|
|
||
| try { | ||
| await importer.launch() | ||
| } catch (failure) { | ||
| if (failure.error === OneSchemaLaunchError.Timeout) { | ||
| // the iframe was blocked, or the embed never acknowledged the launch | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Every failure the embed or the launch deadline produces still fires the `launched` event, so an event-driven host keeps working — but the promise rejects either way, and an unhandled rejection is reported by the browser. Attach a handler even when the event is what you act on: | ||
|
|
||
| ```javascript | ||
| importer.launch().catch(() => { | ||
| // the launched event already reported this | ||
| }) | ||
| ``` | ||
|
|
||
| The one exception is a launch the host abandons itself, through `close()`, `destroy()` or a newer `launch()`: it rejects with `OneSchemaLaunchError.Cancelled` and fires no `launched` event, since the host already knows it ended the attempt. | ||
|
|
||
| `initTimeoutMs` (default `20000`) bounds the whole launch. A launch that is still pending at the deadline rejects with `OneSchemaLaunchError.Timeout` — previously a blocked iframe surfaced as a `fatal` `error` event after the retry schedule ran out. The deadline cannot be turned off: `0`, a negative number and a non-finite number all fall back to the default, because a launch that never settles cannot be reported. | ||
|
|
||
| ### The `success` payload is discriminated | ||
|
|
||
| `OneSchemaImportResult` was `Record<string, any>` and the payload's shape depended on the import strategy. It is now a union tagged with how the data was delivered: | ||
|
|
||
| ```typescript | ||
| importer.on("success", (result) => { | ||
| switch (result.type) { | ||
| case "local": | ||
| case "file-upload": | ||
| return saveRows(result.data) | ||
| case "webhook": | ||
| return console.log(result.eventId, result.responses) | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| Read `result.data` instead of the untagged payload, and branch on `result.type` rather than checking which keys are present. The tag comes from the configured `importConfig.type`, so a `local` import that reports no rows still arrives as `local`. `launchSession()` has no import config, so a server-created session falls back to the payload's shape and reports a file-upload delivery as `local`. | ||
|
|
||
| ### `success` and `cancel` handlers are awaited | ||
|
|
||
| A handler returning a promise now holds the resume token and `autoClose` until it settles, bounded by `handlerTimeoutMs` (default `30000`; raise it for handlers that ship rows to a slow or distant backend, and `0` waits forever). Two things are observable in an existing integration: | ||
|
|
||
| - `autoClose` runs after the handler instead of before it, so a slow handler delays closing the importer. | ||
| - An exception a handler used to throw into the host's own error boundary is delivered to the `error` event instead, with the thrown value on `error.cause`. | ||
|
|
||
| ```javascript | ||
| importer.on("success", async (result) => { | ||
| if (result.type === "webhook") { | ||
| return | ||
| } | ||
|
|
||
| await fetch("/import", { method: "POST", body: JSON.stringify(result.data) }) | ||
|
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
|
||
| // the importer closes after this resolves | ||
| }) | ||
| ``` | ||
|
|
||
| A handler that has not settled by `handlerTimeoutMs` gets an `error` event and the session is cleaned up without it. | ||
|
|
||
| ### `parentId` is gone | ||
|
|
||
| Pass the element itself. `parentId` was resolved once, at construction, so it silently fell back to `document.body` whenever the container was not in the DOM yet — the single most common cause of "the importer rendered in the wrong place". | ||
|
|
||
| ```javascript | ||
| // 0.7.7 | ||
| oneschemaImporter({ clientId, parentId: "oneschema-container" }) | ||
|
|
||
| // 0.8 | ||
| oneschemaImporter({ | ||
| clientId, | ||
| parent: document.getElementById("oneschema-container") ?? undefined, | ||
| }) | ||
| ``` | ||
|
|
||
| ### Each instance owns its iframe | ||
|
|
||
| Instances no longer share a single `_oneschema-iframe` element. Anything that looked that element up by id should hold `importer.iframe` instead, and `destroy()` removes the iframe the instance created along with its window message listener. | ||
|
|
||
| ### `status` replaces the underscore-prefixed internals | ||
|
|
||
| `_hasAttemptedLaunch`, `_launch`, `_initWithRetry` and `_resetSession` are no longer part of the published surface. `importer.status` — `"idle"`, `"launching"`, `"launched"` or `"destroyed"` — is the supported way to ask where an instance is in its lifecycle. | ||
|
|
||
| ### `devMode` defaults to `false` | ||
|
|
||
| It used to default to `!!(process.env.NODE_ENV !== "production")`, evaluated in your bundle at import time, which both guessed at your intent and threw `ReferenceError: process is not defined` when the ESM build was loaded without a `process` shim (CDN, import maps, Deno, workers). Pass it explicitly, wired to your own build condition, if you want the iframe shown when a launch fails: | ||
|
|
||
| ```javascript | ||
| oneschemaImporter({ clientId, devMode: import.meta.env.DEV }) | ||
| ``` | ||
|
|
||
| ### The embed must be on the matching version | ||
|
|
||
| The SDK stamps each launch attempt with an `embedInitId` and requires the embed to echo it, so a reply from an abandoned attempt cannot settle the attempt in flight, and it only accepts messages from the `baseUrl` origin. Both sides ship together: point `baseUrl` at a OneSchema deployment that carries the `0.8` protocol — the default production `baseUrl` does. A self-hosted or pinned embed that does not echo the field cannot be correlated, and every launch against it will time out. | ||
|
|
||
| [LAUNCH-SEQUENCE.md](packages/importer/LAUNCH-SEQUENCE.md) diagrams the whole handshake, including the deadline and how overlapping launches are told apart. | ||
|
|
||
| ## `@oneschema/react` | ||
|
|
||
| `isOpen` is now optional. Omit it and the component is uncontrolled: launch it through the component's `ref`, and the importer closes itself when the import completes, the user cancels, or a fatal error occurs. | ||
|
|
||
| ```jsx | ||
| const importer = useRef(null) | ||
|
|
||
| const launch = async () => { | ||
| try { | ||
| await importer.current.launch() | ||
| } catch (failure) { | ||
| console.error(failure) | ||
| } | ||
| } | ||
|
|
||
| return ( | ||
| <> | ||
| <button onClick={launch}>Import</button> | ||
| <OneSchemaImporter | ||
| ref={importer} | ||
| clientId={clientId} | ||
| userJwt={token} | ||
| templateKey={templateKey} | ||
| onSuccess={saveRows} | ||
| /> | ||
| </> | ||
| ) | ||
| ``` | ||
|
|
||
| The ref exposes `launch(launchParams?)`, which returns the importer's promise, `close(clean?)`, and a `status` getter. | ||
|
|
||
| Supplying `isOpen` keeps the controlled behavior unchanged, including `onRequestClose`, which is only called in that mode. The mode is fixed when the component mounts: switch a component between controlled and uncontrolled by remounting it, not by dropping the prop. | ||
|
|
||
| `onSuccess` and `onCancel` may return promises, which the importer awaits before it closes the session. Their listeners are registered once per importer and read through a ref, so an inline handler no longer causes listeners to be torn off and re-registered mid-emit — the reason an `onSuccess` defined in the render body could miss a `success` that landed on the same commit. Nothing changes in your code for this; if you added a `useCallback` purely to stabilize a handler's identity, it is no longer needed. | ||
|
|
||
| The duplicate-launch warning keys off the importer's `status` rather than the serialized launch params, so it no longer fires for a re-render that changed nothing. | ||
|
|
||
| ## `@oneschema/vue` | ||
|
|
||
| Vue was already uncontrolled — the plugin hands you the core importer — so the change is `launch()`'s promise. Register handlers once in `setup` rather than inside the launch function, and handle the rejection: | ||
|
|
||
| ```vue | ||
| <script setup lang="ts"> | ||
| import { useOneSchemaImporter } from "@oneschema/vue" | ||
|
|
||
| const importer = useOneSchemaImporter() | ||
|
|
||
| importer.on("success", async (result) => { | ||
| if (result.type !== "webhook") { | ||
| await saveRows(result.data) | ||
| } | ||
| }) | ||
|
|
||
| const launch = () => importer.launch().catch(console.error) | ||
| </script> | ||
| ``` | ||
|
|
||
| The plugin destroys its importer when the app unmounts, releasing the window message listener and, under `manageDOM`, the iframe. `useOneSchemaImporter()` throws when the plugin was never installed instead of returning `undefined` typed as an importer. | ||
|
|
||
| ## `@oneschema/angular` | ||
|
|
||
| `OneSchemaService` still extends the importer, so the change is `launch()`'s promise. Call it from a component method that handles the rejection rather than from a template expression, which would leave it unhandled: | ||
|
|
||
| ```typescript | ||
| launch() { | ||
| this.oneschema.launch().catch((failure) => console.error(failure)) | ||
| } | ||
| ``` | ||
|
|
||
| `@oneschema/angular` depends on `@oneschema/importer` directly. If your application imports the core itself, widen your own dependency range to admit the version this wrapper requires. | ||
|
|
||
| ## Codemod | ||
|
|
||
| An unpublished [jscodeshift](https://github.com/facebook/jscodeshift) transform handles the mechanical part. There is no package to install: check the repository out at the release tag and run the transform from disk, so you execute a reviewed revision rather than whatever `main` holds today (`jscodeshift` loads the transform into your Node process, so read it before you run it). | ||
|
|
||
| ```bash | ||
| git clone --depth 1 --branch @oneschema/importer@0.8.0 \ | ||
| https://github.com/oneschema/sdk.git /tmp/oneschema-sdk | ||
|
|
||
| npx jscodeshift@0.15.2 \ | ||
| -t /tmp/oneschema-sdk/scripts/codemod-0.8.cjs \ | ||
| --parser=tsx \ | ||
| src/ | ||
| ``` | ||
|
|
||
| It only touches what it can attribute to the importer: `parentId` inside the options object of a factory imported from an `@oneschema` package, `parentId` on a component imported from one, and `launch()`/`launchSession()` on a local bound to one. Anything else keeps its `parentId` or its `launch()` and gets a `TODO`. It rewrites `parentId` to `parent: document.getElementById(…) ?? undefined` (as an option and as a React prop, since `parent` is `HTMLElement | undefined` and `getElementById` can return `null`), unwraps the exact `const { success } = importer.launch(…)` into an `await` inside a `try`/`catch` where the enclosing function is already `async`, awaits a discarded `launch()` in an `async` function, and gives a discarded one in a synchronous function a `.catch()` that logs the failure for you to replace. Everything it cannot decide safely — a `success` payload read without a `type` check, a destructured `launch()` in a non-`async` function or one binding more than `success`, a launch call whose receiver it cannot attribute, a `_`-prefixed member — is left in place with a `TODO(oneschema-0.8)` comment. Every rewrite and every `TODO` is listed in the run's summary, so a plain-JavaScript codebase still gets the list of call sites to walk. Add `--dry --print` to preview without writing. | ||
|
|
||
| TypeScript flags the rest once the old types are gone, so a typed codebase does not need the codemod to find its call sites — only to save the typing. | ||
|
|
||
| ## Checklist | ||
|
|
||
| - [ ] every `launch()` and `launchSession()` call site awaits the promise or attaches a `.catch()` | ||
| - [ ] `success` handlers narrow on `result.type` | ||
| - [ ] `parentId` replaced with `parent` | ||
| - [ ] `devMode` passed explicitly if you relied on it in development | ||
| - [ ] `handlerTimeoutMs` raised if your `success` handler can legitimately take longer than 30 seconds | ||
| - [ ] `baseUrl` points at a deployment carrying the `0.8` protocol | ||
| - [ ] React: `isOpen` kept only where you want controlled visibility, and `onRequestClose` removed where you do not | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what's the basis of this change?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The basis is that the old default wasn't actually one default — it resolved differently per build artifact of the same published version, and it's not a cosmetic flag.
Unpacking
@oneschema/importer@0.7.7from npm:but the standalone bundle in the same tarball ships
devMode:!1— the expression was already inlined tofalsethere. So a<script src=".../oneschema-importer-0.7.latest.min.js">host gotdevMode: falsein dev and prod, while an npm host got whatever its own bundler did withprocess.env.NODE_ENV: Webpack/Vite/Next define it, so dev builds gottrue; an esbuild or Rollup config with nodefine/processshim leavesprocessundefined and the property read throws where it's evaluated; a shimmedprocesswith noNODE_ENVyieldsundefined !== "production"→true, i.e. dev mode on in production. Same SDK version, three outcomes decided by the consumer's build config rather than by the application.And the flag isn't SDK-local. It goes out on the iframe URL as
dev_mode, and on our side it is persisted on theEmbedrecord (rubeos/src/models/embed.rb), folded into the dedup launch key (rubeos/src/lib/embed_init_dedup.rb, so a host whosedev_modeflips mid-burst gets two launch keys), and sent toAnalytics.identify(embeds_controller.rb:415). In the embed UI it swaps end-user copy for internal diagnostics —EmbeddingMisconfiguredModalrenders the raw configuration table instead ofEmbedding.ReportError, andEmbedState.Uninitializedonly renders a modal at all whendev_mode=true. On the SDK side it also keeps a failed launch's iframe visible instead of honoringautoClose. A wrongtruein production therefore means end users see our config internals and prod embeds are labelled dev in telemetry; a wrongfalsein development only means less debug output.Since it can't be inferred correctly from inside the SDK — a browser bundle has no reliable notion of the host's build mode — 0.8 stops guessing and asks the host to wire it to its own condition (
devMode={import.meta.env.DEV},devMode={!isProd}, etc.).falseis the safe side of the guess, and it's also what the CDN artifact already did, so the change is a no-op for script-tag hosts and for every npm host that builds withNODE_ENV=production.Happy to make it
devMode: undefinedwith the embed deciding instead if you'd rather the default not live in the SDK at all — leaving this open for you.