Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .changeset/explicit-devmode-and-legacy-removal.md
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.

Copy link
Copy Markdown
Member Author

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?

Copy link
Copy Markdown
Contributor

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.7 from npm:

package/dist/main.js:21:    devMode: !!(process.env.NODE_ENV !== "production"),
package/dist/module.js:17:   devMode: !!(process.env.NODE_ENV !== "production"),
package/dist/module.mjs:17:  devMode: !!(process.env.NODE_ENV !== "production"),

but the standalone bundle in the same tarball ships devMode:!1 — the expression was already inlined to false there. So a <script src=".../oneschema-importer-0.7.latest.min.js"> host got devMode: false in dev and prod, while an npm host got whatever its own bundler did with process.env.NODE_ENV: Webpack/Vite/Next define it, so dev builds got true; an esbuild or Rollup config with no define/process shim leaves process undefined and the property read throws where it's evaluated; a shimmed process with no NODE_ENV yields undefined !== "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 the Embed record (rubeos/src/models/embed.rb), folded into the dedup launch key (rubeos/src/lib/embed_init_dedup.rb, so a host whose dev_mode flips mid-burst gets two launch keys), and sent to Analytics.identify (embeds_controller.rb:415). In the embed UI it swaps end-user copy for internal diagnostics — EmbeddingMisconfiguredModal renders the raw configuration table instead of Embedding.ReportError, and EmbedState.Uninitialized only renders a modal at all when dev_mode=true. On the SDK side it also keeps a failed launch's iframe visible instead of honoring autoClose. A wrong true in production therefore means end users see our config internals and prod embeds are labelled dev in telemetry; a wrong false in 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.). false is 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 with NODE_ENV=production.

Happy to make it devMode: undefined with the embed deciding instead if you'd rather the default not live in the SDK at all — leaving this open for you.


`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.
244 changes: 244 additions & 0 deletions MIGRATING-0.8.md
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) })
Comment thread
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
4 changes: 4 additions & 0 deletions packages/importer-angular/projects/oneschema/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,10 @@ export class OneSchemaIframeComponent implements AfterViewInit {
}
```

## Migrating from 0.7

[MIGRATING-0.8.md](https://github.com/oneschema/sdk/blob/main/MIGRATING-0.8.md) walks through the 0.7.7 → 0.8 hop for this package and the core importer it wraps, with a codemod for the mechanical parts.

## Documentation

Please see [📚 OneSchema's documentation](https://docs.oneschema.co/) for [📒 API reference](https://docs.oneschema.co/docs/angular#api-reference) and other helpful guides.
Loading
Loading