@query-farm/vgi 0.25.4 → 0.26.0

package/README.md

@@ -494,6 +494,12 @@ To mount the VGI routes inside a server you already own, use `createVgiWorkerFet
 which returns the `fetch` handler without binding a port. On Cloudflare Workers use
 `createVgiFetch` from `@query-farm/vgi/worker-cf`; both share one implementation.
 
+`createVgiFetch` requires `landingInfo: { name, doc, version }` — the identity the
+landing page and its JSON status document display. `serveVgiWorker` builds it from
+its own required `name`/`doc`/`version`, so only the Cloudflare entry passes it
+explicitly. Without it there is no landing page and no `/vgi-client.js`; see
+[MIGRATION.md](MIGRATION.md).
+
 ## Runtimes & entry points
 
 The package ships a backend-agnostic Arrow facade and selects an implementation at

package/dist/http/client-bundle.d.ts

@@ -0,0 +1,2 @@
+/** The vendored VGI browser client bundle, decoded to its raw bytes. */
+export declare const CLIENT_BUNDLE_BYTES: Uint8Array;

package/dist/http/fetch.d.ts

@@ -1,5 +1,5 @@
 import { type ProtocolConfig } from "../protocol/dispatch.js";
-import type { LandingInfo } from "@query-farm/vgi-rpc";
+import { type LandingInfo } from "./landing.js";
 export interface VgiFetchOptions {
     /** Wire-protocol config (registry + catalogInterface). */
     protocol: Omit<ProtocolConfig, "recoverExchangeState">;
@@ -20,11 +20,20 @@ export interface VgiFetchOptions {
     corsOrigins?: string;
     /** Public source-repository URL, surfaced on the landing page. */
     repositoryUrl?: string;
-    /** Enables the standardized VGI landing surface: `GET /` serves the shared
-     *  landing.html plus a JSON status document carrying this identity, and
-     *  `GET /vgi-client.js` serves the browser client build the page reads the
-     *  catalog with. */
-    landingInfo?: LandingInfo;
+    /** Worker identity for the standardized VGI landing surface: `GET /` serves
+     *  the shared landing.html plus a JSON status document carrying this
+     *  identity, and `GET /vgi-client.js` serves the browser client build the
+     *  page reads the catalog with.
+     *
+     *  Required, and deliberately so. It used to be optional, and omitting it
+     *  silently downgraded `GET /` to vgi-rpc's generic "this is an RPC
+     *  endpoint" placeholder while `GET /vgi-client.js` 404'd — a worker that
+     *  looked deployed but had no catalog tree, no Cupola link, and no ATTACH
+     *  snippet. Nothing failed loudly, so the only way to notice was to open the
+     *  page. `serveVgiWorker` never had the problem because it builds this from
+     *  its required name/doc/version; the CF entry had to remember, and
+     *  vgi-open-meteo shipped for weeks without it. */
+    landingInfo: LandingInfo;
 }
 /**
  * Build a fetch handler suitable for `export default { fetch }` in a CF

package/dist/http/landing-html.d.ts

@@ -0,0 +1,2 @@
+/** The vendored shared landing page, decoded to its raw UTF-8 bytes. */
+export declare const LANDING_HTML_BYTES: Uint8Array;

package/dist/http/landing.d.ts

@@ -0,0 +1,36 @@
+import type { ExtraRouteHandler } from "@query-farm/vgi-rpc";
+/**
+ * Worker identity for the standardized VGI landing surface.
+ *
+ * The shared `landing.html` reads catalog metadata by speaking the VGI protocol
+ * through the client bundle the worker serves beside it, so nothing about the
+ * catalog belongs here. What the protocol has no method for — which worker this
+ * is, what it is called, what version it runs — rides on the JSON status
+ * document at `GET {prefix}/?format=json`.
+ */
+export interface LandingInfo {
+    /** Worker name shown as the page heading, e.g. "ishares". */
+    name: string;
+    /** One-line description shown under the heading. */
+    doc?: string;
+    /** Worker version string shown in the footer. */
+    version?: string;
+    /** Override the Cupola base URL the "Explore" links point at. */
+    cupolaBase?: string;
+}
+/** Default Cupola deployment the page's "Explore" links point at. */
+export declare const DEFAULT_CUPOLA_BASE = "https://cupola.query-farm.services";
+/**
+ * Build the VGI landing surface as a route contributed to vgi-rpc's HTTP
+ * handler.
+ *
+ * Serves two paths, both relative to the handler's mount prefix:
+ *
+ * - `GET {prefix}/` — the shared `landing.html` for browsers, or a JSON status
+ *   document for health checks, `?format=json`, and the page's own identity
+ *   read. Content negotiation matches vgi-python's `LandingPageResource`.
+ * - `GET {prefix}/vgi-client.js` — the browser build the page imports.
+ *
+ * Anything else returns `null`, which lets normal routing continue.
+ */
+export declare function createLandingRoutes(info: LandingInfo): ExtraRouteHandler;

package/dist/index.core.d.ts

@@ -24,7 +24,8 @@ export { metadatasToArrow, arrowToMetadatas } from "./metadata/serialize.js";
 export { PushdownFilters, FilteringOutputCollector, deserializeFilters, buildJoinKeysLookup, ComparisonOp, type Filter, type ConstantFilter, type IsNullFilter, type IsNotNullFilter, type InFilter, type AndFilter, type OrFilter, type StructFilter, formatPushedFilters, reprPushedFilters, } from "./filter-pushdown/index.js";
 export { arrowStateSerializer, EXCHANGE_STATE_SCHEMA, serializeUserState, deserializeUserState } from "./protocol/state-serializer.js";
 export { buildVgiProtocol, type ProtocolConfig } from "./protocol/dispatch.js";
-export type { LandingInfo } from "@query-farm/vgi-rpc";
+export type { LandingInfo } from "./http/landing.js";
+export { createLandingRoutes } from "./http/landing.js";
 export { BindResultSchema, ScanFunctionResultSchema } from "./generated/vgi-protocol-schemas.js";
 export { type AttachOptionSpec, serializeAttachOptionSpec, serializeAttachOptionSpecs, deserializeAttachOptionSpec, deserializeAttachOptionSpecs } from "./catalog/attach-option.js";
 export { type ColumnStatistics, serializeColumnStatistics } from "./util/statistics.js";