@scalar/workspace-store 0.49.3 → 0.51.0

package/dist/persistence/migrations/v2-team-to-local.js

@@ -1,33 +1,58 @@
 /**
- * v2 — collapse every workspace into the local team and drop the namespace concept.
+ * v2 — move to UID-based identity and collapse every workspace into the
+ * local team.
  *
- * Before this migration, workspaces were keyed by `[namespace, slug]` where the
- * namespace doubled as the team identifier (for example `acme-corp/api-workspace`)
- * and a separate `teamUid` field stored the team's UID.
+ * Server-side slugs (both team and workspace) can change at any time and
+ * there is no reliable way for the client to map a stale slug back to its
+ * canonical record. Slugs are still meaningful — they drive the URL — but
+ * the source of truth for "which workspace is this" must be a stable
+ * identifier that lives independently of any human-editable name.
+ *
+ * Before this migration, the workspace store was keyed by `[namespace, slug]`
+ * (with a separate `teamUid` index that was never used for lookups). All
+ * chunk records (meta, documents, ...) were keyed by `${namespace}/${slug}`.
  *
  * After this migration:
- * - The workspace object store is re-created with a new composite key
- *   `[teamSlug, slug]`. The old `teamUid` index is removed; no separate
- *   `teamSlug` index is needed because it is now part of the primary key.
- * - Every workspace is placed under `teamSlug = 'local'`. Team association is
- *   intentionally dropped — every workspace becomes a personal/local one.
- * - The `namespace` field is removed entirely from the record.
- * - When moving a team workspace into the local team would collide with an
- *   existing local slug, a unique suffix (`-2`, `-3`, ...) is appended.
- * - All chunk records (meta, documents, originalDocuments, intermediateDocuments,
- *   overrides, history, auth) are re-keyed to the new `local/<slug>` workspaceId.
- * - Saved tabs and the active tab index are cleared from every workspace's meta
- *   chunk. Tab paths are URLs that embed the old `@<namespace>/<slug>` prefix
- *   and slugs may have been rewritten to resolve collisions, so keeping them
- *   would cause the client to route to stale paths on next load.
+ * - The workspace object store is re-created with `workspaceUid` as its
+ *   primary key. A fresh UUID is generated for every existing record so
+ *   the new identifier is guaranteed to be stable across slug renames.
+ * - Every workspace is relocated to the local team. Both `teamUid` and
+ *   `teamSlug` are set to `'local'`, regardless of where the workspace
+ *   came from. The client only supports a single team workspace going
+ *   forward, so any pre-existing team association is intentionally
+ *   dropped — the app will rebuild the user's team workspace from the
+ *   server on first sign-in.
+ * - Workspace slugs are preserved when possible. If two legacy records
+ *   would collide on the same `[local, <slug>]` pair after collapse, the
+ *   later record gets a unique suffix (`-2`, `-3`, ...). Records that
+ *   were already under the local team keep their slug as-is; team
+ *   workspaces yield first because their slug came from a namespace the
+ *   user no longer controls.
+ * - Two indexes are added to the workspace store:
+ *     - `teamSlug_slug` on `['teamSlug', 'slug']` with `unique: true`,
+ *       so the URL `/@<teamSlug>/<workspaceSlug>` resolves to a single
+ *       workspace and the app can rely on slug-pair uniqueness.
+ *     - `teamUid` on `['teamUid']`, so we can fetch every workspace for a
+ *       team without scanning the store.
+ * - Every chunk store (meta, documents, originalDocuments,
+ *   intermediateDocuments, overrides, history, auth) is recreated with
+ *   `workspaceUid` as its key path (replacing the old `workspaceId`
+ *   field). All chunk records are re-keyed from the legacy
+ *   `${namespace}/${slug}` value to the new `workspaceUid`.
+ * - Saved tabs (`x-scalar-tabs`) and the active tab index
+ *   (`x-scalar-active-tab`) are stripped from every workspace's meta
+ *   chunk. Tab paths embed the old `@<namespace>/<slug>` URL and slugs
+ *   may have been rewritten to resolve collisions, so keeping them would
+ *   route the client to stale paths on next load.
  *
- * All work happens inside the upgrade transaction. The migration awaits every
- * IDB request it queues so the database is fully migrated before `up` resolves
- * — that guarantee is what lets later migrations safely build on this state.
+ * All work happens inside the upgrade transaction. The migration awaits
+ * every IDB request it queues so the database is fully migrated before
+ * `up` resolves — that guarantee is what lets later migrations safely
+ * build on this state.
  */
-/** Tables that store per-workspace chunks keyed by `workspaceId` (single key). */
+/** Tables that store per-workspace chunks keyed by `workspaceUid` (single key). */
 const SINGLE_KEY_CHUNK_TABLES = ['meta'];
-/** Tables that store per-document chunks keyed by `[workspaceId, documentName]`. */
+/** Tables that store per-document chunks keyed by `[workspaceUid, documentName]`. */
 const COMPOSITE_KEY_CHUNK_TABLES = [
     'documents',
     'originalDocuments',
@@ -39,6 +64,12 @@ const COMPOSITE_KEY_CHUNK_TABLES = [
 /**
  * Picks a slug that does not collide with anything in `taken`.
  * Falls back to `<slug>-2`, `<slug>-3`, ... when the desired slug is already used.
+ *
+ * Collapsing every legacy workspace into the local team can produce
+ * `[local, <slug>]` collisions whenever a team workspace shared a slug
+ * with an existing local workspace (or with another team workspace). The
+ * unique `[teamSlug, slug]` index would otherwise reject the upgrade, so
+ * this helper resolves collisions deterministically.
  */
 export const pickUniqueSlug = (desired, taken) => {
     if (!taken.has(desired)) {
@@ -51,51 +82,67 @@ export const pickUniqueSlug = (desired, taken) => {
     return `${desired}-${counter}`;
 };
 /**
- * Computes the new shape for every workspace, preserving local entries under
- * their existing slug and relocating team entries into the local team with a
- * unique slug when needed.
+ * Generates a UUID. Wrapped in a function so tests can stub it and so the
+ * migration does not silently break in environments where `crypto.randomUUID`
+ * is unavailable.
+ */
+const generateUid = () => {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    throw new Error('crypto.randomUUID is not available in this environment; cannot run v2 migration');
+};
+/**
+ * Computes the new shape for every workspace.
+ *
+ * Every record is collapsed into the local team: `teamUid` and `teamSlug`
+ * are both forced to `'local'`. Slug uniqueness is enforced by reserving
+ * the legacy local-team slugs first (they keep their slug verbatim), then
+ * placing every team workspace on top with a `-2`, `-3`, ... suffix when
+ * the desired slug is already taken.
+ *
+ * A fresh `workspaceUid` is generated for every record so the new
+ * identifier is stable across future slug renames.
  */
 export const planWorkspaceMigration = (workspaces) => {
-    // Local slugs that already exist take priority and keep their slug as-is.
+    // Reserve every legacy local slug up front so genuine local workspaces
+    // never lose their slug to a colliding team workspace. Without this the
+    // suffixing would depend on iteration order and could rename the user's
+    // local workspace just because a team workspace happened to come first.
     const reservedSlugs = new Set(workspaces.filter((workspace) => workspace.namespace === 'local').map((workspace) => workspace.slug));
-    const plan = [];
-    for (const workspace of workspaces) {
-        if (workspace.namespace === 'local') {
-            plan.push({
-                before: { namespace: workspace.namespace, slug: workspace.slug },
-                after: {
-                    name: workspace.name,
-                    teamSlug: 'local',
-                    slug: workspace.slug,
-                },
-            });
-            continue;
+    return workspaces.map((workspace) => {
+        const isLocal = workspace.namespace === 'local';
+        // Local workspaces keep their slug because it was already reserved
+        // above. Team workspaces pick a unique slug, suffixing on collision.
+        const slug = isLocal ? workspace.slug : pickUniqueSlug(workspace.slug, reservedSlugs);
+        if (!isLocal) {
+            reservedSlugs.add(slug);
         }
-        const newSlug = pickUniqueSlug(workspace.slug, reservedSlugs);
-        reservedSlugs.add(newSlug);
-        plan.push({
+        return {
             before: { namespace: workspace.namespace, slug: workspace.slug },
             after: {
-                name: workspace.name,
-                // Team association is dropped on purpose — every workspace becomes
-                // local. Slug uniqueness has already been handled above.
+                workspaceUid: generateUid(),
+                // Team membership is intentionally dropped: the client now ships
+                // with a "single team workspace" UX, so any pre-existing team
+                // association is rebuilt from the server on next sign-in.
+                teamUid: 'local',
                 teamSlug: 'local',
-                slug: newSlug,
+                slug,
+                name: workspace.name,
             },
-        });
-    }
-    return plan;
+        };
+    });
 };
-const buildWorkspaceId = (prefix, slug) => `${prefix}/${slug}`;
 /**
  * Keys on the workspace meta record that embed URL paths tied to the old
- * `@<namespace>/<slug>` routing scheme. We strip them during the migration so
- * the client can rebuild them from the current route on next load.
+ * `@<namespace>/<slug>` routing scheme. We strip them during the migration
+ * so the client can rebuild them from the current route on next load.
  */
 const STALE_META_KEYS = ['x-scalar-tabs', 'x-scalar-active-tab'];
 /**
- * Returns a new meta object with stale, URL-bound fields removed. Leaves every
- * other key untouched so color mode, theme, active document, etc. survive.
+ * Returns a new meta object with stale, URL-bound fields removed. Leaves
+ * every other key untouched so color mode, theme, active document, etc.
+ * survive.
  */
 const stripStaleMetaFields = (meta) => {
     if (!meta || typeof meta !== 'object') {
@@ -113,101 +160,112 @@ const requestAsPromise = (req) => new Promise((resolve, reject) => {
     req.onerror = () => reject(req.error);
 });
 /**
- * Re-keys all chunk records belonging to `oldWorkspaceId` so they live under
- * `newWorkspaceId` instead. Always runs so we can also strip stale tab state
- * from the meta chunk, even when the workspace keeps its old id.
- *
- * Returns a Promise that resolves once every queued read/write has completed
- * — this is what lets the migration runner guarantee subsequent migrations
- * see the fully re-keyed state.
+ * Reads every record from a chunk store, returning them tagged with the
+ * legacy `workspaceId` so the caller can remap them to the new
+ * `workspaceUid` once the store has been recreated.
  */
-const remapChunkTables = async (transaction, oldWorkspaceId, newWorkspaceId) => {
-    const idChanged = oldWorkspaceId !== newWorkspaceId;
-    const tasks = [];
-    for (const tableName of SINGLE_KEY_CHUNK_TABLES) {
-        if (!transaction.db.objectStoreNames.contains(tableName)) {
-            continue;
-        }
-        const store = transaction.objectStore(tableName);
-        tasks.push(new Promise((resolve, reject) => {
-            const getRequest = store.get(oldWorkspaceId);
-            getRequest.onerror = () => reject(getRequest.error);
-            getRequest.onsuccess = () => {
-                const record = getRequest.result;
-                if (!record) {
-                    resolve();
-                    return;
-                }
-                // The meta chunk holds x-scalar-tabs with full URL paths built from the
-                // pre-migration namespace/slug. Those paths are no longer routable after
-                // this migration (namespace is dropped and slugs may have been renamed),
-                // so drop them here and let the client rebuild tabs from the live route.
-                const nextData = tableName === 'meta' ? stripStaleMetaFields(record.data) : record.data;
-                if (idChanged) {
-                    store.delete(oldWorkspaceId);
-                }
-                const putRequest = store.put({ ...record, workspaceId: newWorkspaceId, data: nextData });
-                putRequest.onerror = () => reject(putRequest.error);
-                putRequest.onsuccess = () => resolve();
-            };
-        }));
-    }
-    if (idChanged) {
-        for (const tableName of COMPOSITE_KEY_CHUNK_TABLES) {
-            if (!transaction.db.objectStoreNames.contains(tableName)) {
-                continue;
-            }
-            const store = transaction.objectStore(tableName);
-            // Range covering every `[oldWorkspaceId, *]` key.
-            const range = IDBKeyRange.bound([oldWorkspaceId], [oldWorkspaceId, []], false, true);
-            tasks.push(new Promise((resolve, reject) => {
-                const cursorRequest = store.openCursor(range);
-                cursorRequest.onerror = () => reject(cursorRequest.error);
-                cursorRequest.onsuccess = (event) => {
-                    const cursor = event.target.result;
-                    if (!cursor) {
-                        resolve();
-                        return;
-                    }
-                    const value = cursor.value;
-                    cursor.delete();
-                    store.put({ ...value, workspaceId: newWorkspaceId });
-                    cursor.continue();
-                };
-            }));
-        }
+const readLegacyChunkRecords = async (transaction, tableName) => {
+    if (!transaction.db.objectStoreNames.contains(tableName)) {
+        return [];
     }
-    await Promise.all(tasks);
+    const store = transaction.objectStore(tableName);
+    const records = (await requestAsPromise(store.getAll())) ?? [];
+    return records;
 };
 export const v2TeamToLocalMigration = {
-    description: 'Re-key workspace store to [teamSlug, slug]; collapse all workspaces into the local team',
+    description: 'Switch to UID-based identity: workspaceUid primary key, collapse every workspace into the local team',
     up: async ({ db, transaction }) => {
         if (!db.objectStoreNames.contains('workspace')) {
-            // The workspace store must exist after v1; if it does not, something is
-            // very wrong and we should not silently create a new one here.
+            // The workspace store must exist after v1; if it does not, something
+            // is very wrong and we should not silently create a new one here.
             return;
         }
-        // Read every record from the old workspace store before we delete it.
-        // The upgrade transaction stays alive while the `getAll` request is
-        // pending, so the schema mutations below still run in versionchange
-        // mode — which is required for deleteObjectStore / createObjectStore.
+        // Read every legacy record before we drop the old stores. The upgrade
+        // transaction stays alive while these requests are pending, so the
+        // schema mutations below still run in versionchange mode — which is
+        // required for deleteObjectStore / createObjectStore.
         const oldWorkspaceStore = transaction.objectStore('workspace');
         const workspaces = ((await requestAsPromise(oldWorkspaceStore.getAll())) ?? []);
+        // Snapshot every chunk record up front so we can recreate the stores
+        // with the new key paths and then rewrite the records below.
+        const legacySingleKeyChunks = {};
+        for (const tableName of SINGLE_KEY_CHUNK_TABLES) {
+            legacySingleKeyChunks[tableName] = await readLegacyChunkRecords(transaction, tableName);
+        }
+        const legacyCompositeKeyChunks = {};
+        for (const tableName of COMPOSITE_KEY_CHUNK_TABLES) {
+            const records = await readLegacyChunkRecords(transaction, tableName);
+            legacyCompositeKeyChunks[tableName] = records;
+        }
         const plan = planWorkspaceMigration(workspaces);
-        // The workspace store's keyPath cannot be changed in place, so drop it
-        // and recreate it with the new composite key. No separate `teamSlug`
-        // index is needed because the team slug is the first part of the key.
+        // Map legacy `${namespace}/${slug}` to the new workspaceUid so chunk
+        // records can be re-keyed in a single pass below.
+        const legacyIdToWorkspaceUid = new Map();
+        for (const { before, after } of plan) {
+            legacyIdToWorkspaceUid.set(`${before.namespace}/${before.slug}`, after.workspaceUid);
+        }
+        // Recreate the workspace store with workspaceUid as the primary key,
+        // plus the indexes the runtime relies on for slug-based lookups and
+        // team-scoped queries. The `[teamSlug, slug]` index is unique so we
+        // never end up with two workspaces racing for the same URL.
         db.deleteObjectStore('workspace');
-        const newWorkspaceStore = db.createObjectStore('workspace', { keyPath: ['teamSlug', 'slug'] });
-        // Re-key all chunk tables in parallel so the entire migration finishes in
-        // a single round-trip. Awaiting before `up` resolves is what guarantees
-        // any future migration appended after this one observes the post-v2
-        // state — without this await, IDB callbacks would still be in flight.
-        await Promise.all(plan.map(async ({ before, after }) => {
-            const oldWorkspaceId = buildWorkspaceId(before.namespace, before.slug);
-            const newWorkspaceId = buildWorkspaceId(after.teamSlug, after.slug);
+        const newWorkspaceStore = db.createObjectStore('workspace', { keyPath: 'workspaceUid' });
+        newWorkspaceStore.createIndex('teamSlug_slug', ['teamSlug', 'slug'], { unique: true });
+        newWorkspaceStore.createIndex('teamUid', ['teamUid']);
+        // Recreate every chunk store with the new `workspaceUid` key path. We
+        // drop and recreate (rather than rewriting records in place) because
+        // changing an object store's key path is not supported by IndexedDB.
+        for (const tableName of SINGLE_KEY_CHUNK_TABLES) {
+            if (transaction.db.objectStoreNames.contains(tableName)) {
+                db.deleteObjectStore(tableName);
+            }
+            db.createObjectStore(tableName, { keyPath: 'workspaceUid' });
+        }
+        for (const tableName of COMPOSITE_KEY_CHUNK_TABLES) {
+            if (transaction.db.objectStoreNames.contains(tableName)) {
+                db.deleteObjectStore(tableName);
+            }
+            db.createObjectStore(tableName, { keyPath: ['workspaceUid', 'documentName'] });
+        }
+        // Write the migrated workspace records. We do this after creating all
+        // stores so the upgrade transaction commits a fully-formed schema even
+        // if there are zero legacy records to migrate.
+        for (const { after } of plan) {
             newWorkspaceStore.put(after);
-            await remapChunkTables(transaction, oldWorkspaceId, newWorkspaceId);
-        }));
+        }
+        // Re-key every chunk record from the legacy `${namespace}/${slug}` to
+        // the new workspaceUid. Records belonging to a workspace that no
+        // longer exists (orphans) are dropped — they have no meaning without
+        // their parent workspace.
+        for (const tableName of SINGLE_KEY_CHUNK_TABLES) {
+            const store = transaction.objectStore(tableName);
+            for (const record of legacySingleKeyChunks[tableName] ?? []) {
+                const workspaceUid = legacyIdToWorkspaceUid.get(record.workspaceId);
+                if (!workspaceUid) {
+                    continue;
+                }
+                const { workspaceId: _legacyId, ...rest } = record;
+                // The meta chunk holds x-scalar-tabs with full URL paths built
+                // from the pre-migration namespace/slug. Those paths are no
+                // longer routable after collapsing into the local team (and slugs
+                // may have been suffixed on collision), so drop them here and
+                // let the client rebuild tabs from the live route.
+                const nextData = tableName === 'meta'
+                    ? stripStaleMetaFields(rest.data)
+                    : rest.data;
+                store.put({ ...rest, data: nextData, workspaceUid });
+            }
+        }
+        for (const tableName of COMPOSITE_KEY_CHUNK_TABLES) {
+            const store = transaction.objectStore(tableName);
+            for (const record of legacyCompositeKeyChunks[tableName] ?? []) {
+                const workspaceUid = legacyIdToWorkspaceUid.get(record.workspaceId);
+                if (!workspaceUid) {
+                    continue;
+                }
+                const { workspaceId: _legacyId, ...rest } = record;
+                store.put({ ...rest, workspaceUid });
+            }
+        }
     },
 };

package/dist/request-example/builder/body/build-request-body.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-request-body.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/build-request-body.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0DAA0D,CAAA;AAKjG,KAAK,QAAQ,GAAG;IACd,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,CACH;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;KACd,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CACJ,EAAE,CAAA;CACJ,CAAA;AAED,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,YAAY,CAAA;IAClB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;KACd,EAAE,CAAA;CACJ,CAAA;AAED,KAAK,GAAG,GAAG;IACT,IAAI,EAAE,KAAK,CAAA;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,GAAG,CAAA;AAKrD;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,iBAAiB,GAAG,SAAS;AAC1C,qCAAqC;AACrC,oBAAuB;AACvB,sEAAsE;AACtE,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KACvD,WAAW,GAAG,IAwMhB,CAAA"}
+{"version":3,"file":"build-request-body.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/build-request-body.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0DAA0D,CAAA;AAKjG,KAAK,QAAQ,GAAG;IACd,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,CACH;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;KACd,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CACJ,EAAE,CAAA;CACJ,CAAA;AAED,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,YAAY,CAAA;IAClB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;KACd,EAAE,CAAA;CACJ,CAAA;AAED,KAAK,GAAG,GAAG;IACT,IAAI,EAAE,KAAK,CAAA;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,GAAG,CAAA;AAKrD;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,iBAAiB,GAAG,SAAS;AAC1C,qCAAqC;AACrC,oBAAuB;AACvB,sEAAsE;AACtE,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KACvD,WAAW,GAAG,IAyMhB,CAAA"}

package/dist/request-example/builder/body/build-request-body.js

@@ -97,7 +97,7 @@ requestBodyCompositionSelection) => {
         // Convert object properties to form fields
         for (const [key, value] of Object.entries(example.value)) {
             if (key && value !== undefined && value !== null) {
-                const stringValue = typeof value === 'string' ? value : String(value);
+                const stringValue = typeof value === 'object' && value !== null ? JSON.stringify(unpackProxyObject(value)) : String(value);
                 result.value.push({
                     key,
                     value: stringValue,

package/dist/request-example/builder/build-request.d.ts

@@ -1,15 +1,28 @@
+import { type Result } from '@scalar/helpers/types/result';
 import type { RequestFactory } from '../../request-example/builder/request-factory.js';
+import { type ResolveRequestFactoryUrlError } from '../../request-example/builder/resolve-request-factory-url.js';
 /**
  * The payload to build a request, useful when bypassing limitations of the browser Request object
  */
 export type RequestPayload = [string, RequestInit];
+/**
+ * Resolved request URL string (path vars, operation query, **security query**
+ * params, env substitution, reserved-query rules) without proxy rewriting —
+ * aligned with {@link buildRequest} before `redirectToProxy`.
+ *
+ * By default allows incomplete merged URLs (same as permissive copy / preview); pass
+ * `allowMissingRequestServerBase: false` to enforce a complete absolute URL.
+ */
+export declare const resolveExecutableRequestUrl: (request: RequestFactory, envVariables: Record<string, string>, resolveOptions?: {
+    allowMissingRequestServerBase?: boolean;
+}) => string;
 /**
  * Built request response
  *
  * We no longer return a Request object, but a tuple of [url, init] that maps directly to the fetch() argument list so
  * we can do things that the browser doesn't allow like GET + body
  * */
-type BuildRequestResponse = {
+export type BuildRequestData = {
     /** Create a new request payload object with the replaced values ready to be sent to the server */
     requestPayload: RequestPayload;
     /** The abort controller */
@@ -17,8 +30,16 @@ type BuildRequestResponse = {
     /** The flag indicating if the request is being proxied */
     isUsingProxy: boolean;
 };
+/** Catch-all code when an unexpected synchronous error escapes a helper during request construction. */
+export declare const BUILD_REQUEST_FAILED: "BUILD_REQUEST_FAILED";
+export type BuildRequestFailureCode = ResolveRequestFactoryUrlError | typeof BUILD_REQUEST_FAILED;
+export type BuildRequestResult = Result<BuildRequestData, BuildRequestFailureCode>;
 export declare const buildRequest: (request: RequestFactory, options: {
     envVariables: Record<string, string>;
-}) => BuildRequestResponse;
-export {};
+    /**
+     * When true, allows an empty resolved server base URL (embedded modal, API reference callbacks, tests).
+     * @default false
+     */
+    allowMissingRequestServerBase?: boolean;
+}) => BuildRequestResult;
 //# sourceMappingURL=build-request.d.ts.map

package/dist/request-example/builder/build-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-request.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/build-request.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAA;AAK/E;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAElD;;;;;KAKK;AACL,KAAK,oBAAoB,GAAG;IAC1B,kGAAkG;IAClG,cAAc,EAAE,cAAc,CAAA;IAC9B,2BAA2B;IAC3B,UAAU,EAAE,eAAe,CAAA;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,eAAO,MAAM,YAAY,GACvB,SAAS,cAAc,EACvB,SAAS;IACP,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC,KACA,oBA2JF,CAAA"}
+{"version":3,"file":"build-request.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/build-request.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,8BAA8B,CAAA;AAOnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAA;AAC/E,OAAO,EACL,KAAK,6BAA6B,EAEnC,MAAM,uDAAuD,CAAA;AAK9D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAuClD;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,cAAc,EACvB,cAAc,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,iBAAiB;IAAE,6BAA6B,CAAC,EAAE,OAAO,CAAA;CAAE,KAC3D,MAyBF,CAAA;AAED;;;;;KAKK;AACL,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kGAAkG;IAClG,cAAc,EAAE,cAAc,CAAA;IAC9B,2BAA2B;IAC3B,UAAU,EAAE,eAAe,CAAA;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAA;AAEnE,MAAM,MAAM,uBAAuB,GAAG,6BAA6B,GAAG,OAAO,oBAAoB,CAAA;AAEjG,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAAA;AAElF,eAAO,MAAM,YAAY,GACvB,SAAS,cAAc,EACvB,SAAS;IACP,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC;;;OAGG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAA;CACxC,KACA,kBAMF,CAAA"}

package/dist/request-example/builder/build-request.js

@@ -1,18 +1,79 @@
+import { X_SCALAR_DATE, X_SCALAR_DNT, X_SCALAR_REFERER, X_SCALAR_USER_AGENT } from '@scalar/helpers/http/scalar-headers';
 import { replaceEnvVariables } from '@scalar/helpers/regex/replace-variables';
+import { err, ok } from '@scalar/helpers/types/result';
+import { safeRun } from '@scalar/helpers/types/safe-run';
 import { redirectToProxy, shouldUseProxy } from '@scalar/helpers/url/redirect-to-proxy';
 import { encode as encodeBase64 } from 'js-base64';
 import { buildRequestCookieHeader } from '../../request-example/builder/header/build-request-cookie-header.js';
 import { applyAllowReservedToUrl } from '../../request-example/builder/helpers/apply-allow-reserved-to-url.js';
-import { resolveRequestFactoryUrl } from '../../request-example/builder/resolve-request-factory-url.js';
+import { resolveRequestFactoryUrl, } from '../../request-example/builder/resolve-request-factory-url.js';
 import { contextFunctions, isContextFunctionName } from '../../request-example/functions.js';
-export const buildRequest = (request, options) => {
-    /** Replace the value with the environment variable or context function */
-    const replace = (value) => {
+const FORBIDDEN_HEADERS = [
+    { header: 'date', scalarHeader: X_SCALAR_DATE },
+    { header: 'dnt', scalarHeader: X_SCALAR_DNT },
+    { header: 'referer', scalarHeader: X_SCALAR_REFERER },
+    { header: 'user-agent', scalarHeader: X_SCALAR_USER_AGENT },
+];
+const formatSecurityValue = (security, replace) => {
+    const substitutedValue = replaceEnvVariables(security.value, replace);
+    if (security.format === 'basic') {
+        return `Basic ${encodeBase64(substitutedValue)}`;
+    }
+    if (security.format === 'bearer') {
+        return `Bearer ${substitutedValue}`;
+    }
+    return substitutedValue;
+};
+const createEnvReplaceFn = (envVariables) => {
+    return (value) => {
         if (isContextFunctionName(value)) {
             return contextFunctions[value].fn() ?? null;
         }
-        return options.envVariables[value] ?? null;
+        return envVariables[value] ?? null;
     };
+};
+/**
+ * Resolved request URL string (path vars, operation query, **security query**
+ * params, env substitution, reserved-query rules) without proxy rewriting —
+ * aligned with {@link buildRequest} before `redirectToProxy`.
+ *
+ * By default allows incomplete merged URLs (same as permissive copy / preview); pass
+ * `allowMissingRequestServerBase: false` to enforce a complete absolute URL.
+ */
+export const resolveExecutableRequestUrl = (request, envVariables, resolveOptions) => {
+    const replace = createEnvReplaceFn(envVariables);
+    const securityQueryParams = new URLSearchParams();
+    if (!request.options?.disableSecurity) {
+        request.security.forEach((security) => {
+            if (security.in !== 'query') {
+                return;
+            }
+            const name = replaceEnvVariables(security.name, replace);
+            securityQueryParams.append(name, formatSecurityValue(security, replace));
+        });
+    }
+    const requestUrl = resolveRequestFactoryUrl(request, {
+        envVariables: replace,
+        securityQueryParams,
+        allowMissingRequestServerBase: resolveOptions?.allowMissingRequestServerBase ?? true,
+    });
+    if (!requestUrl.ok) {
+        throw new Error(requestUrl.message ?? requestUrl.error);
+    }
+    return applyAllowReservedToUrl(requestUrl.data, request.allowedReservedQueryParameters ?? new Set());
+};
+/** Catch-all code when an unexpected synchronous error escapes a helper during request construction. */
+export const BUILD_REQUEST_FAILED = 'BUILD_REQUEST_FAILED';
+export const buildRequest = (request, options) => {
+    const guarded = safeRun(() => buildRequestInner(request, options));
+    if (!guarded.ok) {
+        return err(BUILD_REQUEST_FAILED, guarded.error);
+    }
+    return guarded.data;
+};
+const buildRequestInner = (request, options) => {
+    /** Replace the value with the environment variable or context function */
+    const replace = createEnvReplaceFn(options.envVariables);
     /** Create a new abort controller */
     const controller = new AbortController();
     /** Create a new headers object with the replaced values */
@@ -60,16 +121,7 @@ export const buildRequest = (request, options) => {
             // - For 'basic': prefix with 'Basic' and base64-encode the value (username:password).
             // - For 'bearer': prefix with 'Bearer'.
             // - Otherwise: use the substituted value as is (for API keys, etc).
-            const securityValue = (() => {
-                const substitutedValue = replaceEnvVariables(security.value, replace);
-                if (security.format === 'basic') {
-                    return `Basic ${encodeBase64(substitutedValue)}`;
-                }
-                if (security.format === 'bearer') {
-                    return `Bearer ${substitutedValue}`;
-                }
-                return substitutedValue;
-            })();
+            const securityValue = formatSecurityValue(security, replace);
             if (security.in === 'header') {
                 // Set the header (use replaced header name so {{ env }} placeholders work)
                 headers.append(name, securityValue);
@@ -89,10 +141,15 @@ export const buildRequest = (request, options) => {
         });
     }
     /** Resolve the request URL with the replaced values */
-    const requestUrl = resolveRequestFactoryUrl(request, {
+    const requestUrlResult = resolveRequestFactoryUrl(request, {
         envVariables: replace,
         securityQueryParams: securityQueryParams,
+        allowMissingRequestServerBase: options.allowMissingRequestServerBase,
     });
+    if (!requestUrlResult.ok) {
+        return err(requestUrlResult.error, requestUrlResult.message);
+    }
+    const requestUrl = requestUrlResult.data;
     /** Check if the request should be proxied */
     const isUsingProxy = shouldUseProxy(request.proxyUrl, requestUrl);
     /** Create a new cookies array with the replaced values */
@@ -112,10 +169,24 @@ export const buildRequest = (request, options) => {
     if (cookieHeader) {
         headers.set(cookieHeader.name, cookieHeader.value);
     }
+    /**
+     * Browsers strip some forbidden headers from outgoing requests.
+     * For a small, explicit allowlist we mirror those values to `X-Scalar-*`
+     * so proxy/Electron can apply them server-side.
+     */
+    if (isUsingProxy || request.options?.isElectron) {
+        FORBIDDEN_HEADERS.forEach(({ header, scalarHeader }) => {
+            const headerValue = headers.get(header);
+            if (headerValue) {
+                headers.set(scalarHeader, headerValue);
+                headers.delete(header);
+            }
+        });
+    }
     /** Encode the URL with the allowed reserved query parameters */
     const encodedUrl = applyAllowReservedToUrl(requestUrl, request.allowedReservedQueryParameters ?? new Set());
     const finalUrl = isUsingProxy ? redirectToProxy(request.proxyUrl, encodedUrl) : encodedUrl;
-    return {
+    return ok({
         requestPayload: [
             finalUrl,
             {
@@ -133,5 +204,5 @@ export const buildRequest = (request, options) => {
         ],
         controller,
         isUsingProxy,
-    };
+    });
 };

package/dist/request-example/builder/index.d.ts

@@ -1,6 +1,6 @@
 export { getExampleFromBody } from './body/get-request-body-example.js';
 export { getSelectedBodyContentType } from './body/get-selected-body-content-type.js';
-export { type RequestPayload, buildRequest } from './build-request.js';
+export { BUILD_REQUEST_FAILED, type BuildRequestData, type BuildRequestFailureCode, type BuildRequestResult, type RequestPayload, buildRequest, resolveExecutableRequestUrl, } from './build-request.js';
 export { deSerializeParameter } from './header/de-serialize-parameter.js';
 export { filterGlobalCookie } from './header/filter-global-cookies.js';
 export { serializeContentValue, serializeDeepObjectStyle, serializeFormStyle, serializeFormStyleForCookies, serializePipeDelimitedStyle, serializeSimpleStyle, serializeSpaceDelimitedStyle, } from './header/serialize-parameter.js';
@@ -11,6 +11,7 @@ export { getResolvedUrl } from './helpers/get-resolved-url.js';
 export { getServerVariables } from './helpers/get-server-variables.js';
 export type { RequestFactory } from './request-factory.js';
 export { requestFactory } from './request-factory.js';
+export { INVALID_REQUEST_FACTORY_URL, MISSING_REQUEST_SERVER_BASE, type ResolveRequestFactoryUrlError, type ResolveRequestFactoryUrlResult, resolveRequestFactoryUrl, } from './resolve-request-factory-url.js';
 export { buildRequestSecurity } from './security/build-request-security.js';
 export type { ApiKeyObjectSecret, HttpObjectSecret, OAuth2ObjectSecret, OAuthFlowAuthorizationCodeSecret, OAuthFlowClientCredentialsSecret, OAuthFlowImplicitSecret, OAuthFlowPasswordSecret, OAuthFlowsObjectSecret, OpenIdConnectObjectSecret, SecuritySchemeObjectSecret, } from './security/secret-types.js';
 //# sourceMappingURL=index.d.ts.map