Skip to content

feat(sheets): let a host send the grid's requests and upload bytes - #66

Merged
yyyyaaa merged 3 commits into
mainfrom
feat/sheets-transport
Nov 17, 2026
Merged

yyyyaaa merged 3 commits into
mainfrom
feat/sheets-transport

Conversation

@yyyyaaa

@yyyyaaa yyyyaaa commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

A host can now send the grid's network traffic itself. Constructive Desktop needs this: its window loads from http://localhost:5173 (dev) or file://, an origin no API lists in its cors_settings, and since constructive-io/constructive#1974 the GraphQL server refuses unlisted origins.

SheetsConfig.transport

const config: SheetsConfig = {
  endpoint,
  databaseId,
  auth: { mode: 'embedded', getToken },
  storage: { endpoint: storageEndpoint },
  transport: { fetch: hostFetch, put: hostPut }, // SheetsFetchFn, SheetsPutFn
};
  • fetch carries every GraphQL request: data, storage, and auth in standalone mode. It answers like the global fetch.
  • put carries each upload's bytes to its presigned URL, with exactly the payload's signed headers: the grid's file columns and createSheetsUpload (uploadToFilesTable takes it as storage.put). It resolves with the answer whatever its status, and rejects only when no answer came.
  • Sheets keeps its own handling of every answer: the bearer token, 401 and onAuthError, partial rows, error codes, an expired upload URL renewed once.
  • Either part is optional; without it the page's own fetch / XMLHttpRequest sends that part, as before. An injected execute, storage.execute or executeUpload still replaces it.

One upload path

  • An upload's UploadRoute pairs its request (the mutation that issues a signed URL) with its put; each path builds it from its storage transport (createUploadRoute, discoveredUploadRoute), and transferFile(file, route, options) takes it.
  • The page's own PUT (XHR with progress, else fetch) now has the same contract as a host's put, so one sender turns any answer into an upload error, for both.
  • Only a cancel of the upload's own signal is an AbortError. Before, any AbortError ended the upload like a user cancel, so an upload that failed elsewhere could sit at "uploading" with no error.
  • presignedPut (earlier API) sends exactly what it sent before.

Docs

  • docs/HOST_INTEGRATION.md: a "Host transport" section.
  • docs/EMBEDDING.md: the grid's container must be a flex column with min-height: 0 (the Sheets root is display: contents), clipped with overflow: clip. A block container hid the status bar, and an overflow: hidden one could be scrolled by the grid's focus, away from its overlay editors.

🤖 Generated with Claude Code

https://claude.ai/code/session_017WbsG8xSPVNk24sN2QThLw

SheetsConfig.transport takes a host's fetch for every GraphQL request (data,
storage, and standalone auth) and a put for every upload's bytes, so a host
whose page origin no API lists for CORS, such as a desktop app, can send them
from its own process. Sheets keeps its own handling of each answer: the bearer
token, 401 and onAuthError, partial rows, an expired upload URL renewed once.

The page's own PUT now has the same contract as a host's put, so one place turns
any answer into an upload error, and only a cancel of the upload's own signal is
an AbortError: an upload that failed for another reason never ends like a cancel.
The Sheets root is display: contents, so its toolbar and grid are children of
the host's container. In a block container the grid is as tall as the container
plus the toolbar and its status bar falls out of view, and a container that is
overflow: hidden can be scrolled by the grid's focus, away from its overlay editors.
@luxor-code-review

luxor-code-review Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Review complete. No blocking issues — approved ✅; 1 nitpick below.

🧹 Nitpicks (1) — 🟢 1 low
  • 🟢 Export the SheetsStorageTransport type the docs name (index.ts:8) — The new "Host transport" docs tell hosts to "set put on that storage object (SheetsStorageTransport.put)" for uploadToFilesTable (packages/sheets/docs/HOST_INTEGRATION.md:198), and UploadToFilesTableOptions.storage is typed SheetsStorageTransport (packages/sheets/src/uploads/upload-to-files-table.ts:25).

This PR threads an optional host transport through the Sheets data, auth, and storage upload paths, letting embedding hosts intercept or proxy network calls instead of the package falling back to window.fetch/XHR.

Files Change
packages/sheets/src/context/sheets-context.ts, index.ts Introduces the SheetsTransport types and re-exports them along with the relocated UploadProgressEvent.
packages/sheets/src/context/sheets-execute.ts, sheets-upload-discovery.ts, sheets-upload-presigned.ts Route GraphQL and presigned-upload calls through transport.fetch when provided; presigned PUTs go through the host put seam.
packages/sheets/src/auth/auth-execute.ts Applies the same transport selection to bearer-authenticated requests with unchanged 401/onAuthError handling.
packages/sheets/src/uploads/plane-upload.ts, column-storage.ts Preserves signal/abort semantics and progress reporting (100% only after successful PUT) across the host put fallback.
packages/sheets/src/uploads/__tests__/host-transport.test.tsx, sheets-execute.test.ts Integration tests covering host transport selection, abort-vs-failure mapping, and expired-URL renewal.
packages/sheets/README.md, docs/EMBEDDING.md, docs/HOST_INTEGRATION.md Document the host transport contract for embedding hosts.

Review verified transport threading, abort semantics, and API-compat concerns across all changed files; one minor export gap remains.

Reviewed commit: bdddce8

transferFile took the requester and the host's put as two positional arguments,
and every caller split them out of the same storage transport. An UploadRoute
names the pair: request asks the storage API for a signed URL, put sends the
bytes. Each upload path builds its route from its storage in one place
(createUploadRoute for the plane's own mutation, discoveredUploadRoute for the
two discovery paths), and putFile keeps its earlier (url, body, options) shape.
@yyyyaaa
yyyyaaa merged commit 7767366 into main Nov 17, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant