@bendyline/gezel-sdk 1.1.7 → 1.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/page.d.ts +131 -6
  2. package/package.json +2 -2
package/dist/page.d.ts CHANGED
@@ -5,7 +5,8 @@
5
5
  * The runtime object is injected server-side by the daemon
6
6
  * (`packages/service/src/http/routes/page-api-shim.ts` splices the shim
7
7
  * into every `text/html` response served from the `type` preview source),
8
- * so pages never bundle an implementation — this module exists so gilde
8
+ * so hosted pages need no bundled implementation (the demo publisher/exporter supplies the same
9
+ * components and fonts) — this module exists so gilde
9
10
  * page authors and the host UI relay share one contract. The postMessage
10
11
  * envelope behind it is validated by the zod schemas in
11
12
  * `@bendyline/gezel` (`packages/core/src/schemas/page-bridge.ts`); the
@@ -24,8 +25,8 @@
24
25
  * and `data.*` travel as same-origin fetches against the head API under
25
26
  * the visitor's cookie; `data.watch` polls; `refresh()` reloads. The
26
27
  * page still never sees a credential.
27
- * - `demo` — a raw file opened outside gezel entirely. The real shim is
28
- * never present there; gilde ships a paste-in stub that defines
28
+ * - `demo` — a published preview or exported offline page. The shared demo
29
+ * bootstrap defines
29
30
  * `window.gezel` only when the real one is absent.
30
31
  *
31
32
  * Guard accordingly: `if (window.gezel) { ... }`.
@@ -157,11 +158,33 @@ interface GezelPageWatchOptions {
157
158
  intervalMs?: number;
158
159
  }
159
160
  /**
160
- * Read-only access to the project's files, scoped to what the page's
161
+ * Read access to the project's files, scoped to what the page's
161
162
  * manifest declared readable. Out-of-scope paths reject with code
162
- * `'not-allowed'`; writes happen through {@link GezelPageToolsApi} only.
163
+ * `'not-allowed'`. Uploads use separately declared import destinations;
164
+ * other writes happen through {@link GezelPageToolsApi}.
163
165
  */
164
166
  interface GezelPageDataApi {
167
+ /** Explicit manifest destinations and current workspace write availability. */
168
+ importTargets(): Promise<GezelImportTarget[]>;
169
+ /** Copies selected files, keeping both on name conflicts. Results include partial failures.
170
+ * Embedded desktop only; demo adapters keep files in memory. Maximum 100 files/batch,
171
+ * 256 MiB/file (destinations can lower this). Cancellation does not undo completed files. */
172
+ importFiles(files: Iterable<File>, opts: {
173
+ target: string;
174
+ signal?: AbortSignal;
175
+ onProgress?: (progress: {
176
+ completed: number;
177
+ total: number;
178
+ name: string;
179
+ }) => void;
180
+ }): Promise<GezelImportResult[]>;
181
+ /**
182
+ * Open a declared file in Gezel's existing file viewer (CSV table,
183
+ * spreadsheet, document, etc.). Checks the manifest's read scope and
184
+ * file existence before navigating. Embedded mode only; rejects with
185
+ * 'unavailable' in standalone browser and serve modes.
186
+ */
187
+ open(path: string, opts?: GezelPageSourceOptions): Promise<void>;
165
188
  /**
166
189
  * Read one file. Resolves to a string for `'text'`, a parsed value for
167
190
  * `'json'`, or a `Uint8Array` for `'bytes'` (see
@@ -187,12 +210,61 @@ interface GezelPageDataApi {
187
210
  */
188
211
  url(path: string, opts?: GezelPageSourceOptions): string;
189
212
  }
213
+ /** A queryable table backed by a file/directory in the page's declared reads. */
214
+ interface GezelPageTable {
215
+ /** Stable SQL identifier issued by the host. Do not derive this from a filename. */
216
+ name: string;
217
+ title: string;
218
+ source: GezelPageReadSource;
219
+ /** Original workspace file, or the connector's artifact table directory. */
220
+ path: string;
221
+ rows: number;
222
+ columnCount: number;
223
+ updatedAt?: string;
224
+ schemaInferred: boolean;
225
+ }
226
+ interface GezelPageTableSchema {
227
+ op: 'describe';
228
+ table: GezelPageTable;
229
+ columns: Array<{
230
+ name: string;
231
+ type: 'BOOLEAN' | 'BIGINT' | 'DOUBLE' | 'VARCHAR' | 'DATE' | 'TIMESTAMP' | 'JSON';
232
+ role: 'time' | 'dimension' | 'measure' | 'identifier' | 'attribute';
233
+ description?: string;
234
+ unit?: string;
235
+ cardinalityHint?: string;
236
+ examples?: string[];
237
+ }>;
238
+ description?: string;
239
+ grain?: string;
240
+ }
241
+ interface GezelPageTableQuery {
242
+ op: 'query';
243
+ rows: Record<string, unknown>[];
244
+ columns: string[];
245
+ truncated: boolean;
246
+ limit: number;
247
+ tablesInScope: string[];
248
+ }
249
+ /** Read-only DuckDB access in embedded/serve mode on hosts with a query engine.
250
+ * Permissions are checked again on every call; no table names grant authority. */
251
+ interface GezelPageTablesApi {
252
+ list(): Promise<GezelPageTable[]>;
253
+ describe(table: string): Promise<GezelPageTableSchema>;
254
+ /** One read-only statement. Default limit 100, max 1000 rows and 1 MiB.
255
+ * `tables` can narrow the readable scope, never expand it. */
256
+ query(sql: string, opts?: {
257
+ tables?: string[];
258
+ limit?: number;
259
+ }): Promise<GezelPageTableQuery>;
260
+ }
190
261
  /** The host UI theme as seen by the page. */
191
262
  interface GezelPageTheme {
192
263
  mode: 'light' | 'dark';
193
264
  }
194
265
  /** Host UI state the page can mirror. */
195
266
  interface GezelPageUiApi {
267
+ components: GezelPageComponents;
196
268
  /** The current theme. Live — reflects the host's latest pushed value. */
197
269
  theme: GezelPageTheme;
198
270
  /**
@@ -202,6 +274,58 @@ interface GezelPageUiApi {
202
274
  */
203
275
  onTheme(cb: (t: GezelPageTheme) => void): () => void;
204
276
  }
277
+ interface GezelPageFile {
278
+ source?: GezelPageReadSource;
279
+ path: string;
280
+ name?: string;
281
+ size?: number;
282
+ mtime?: number;
283
+ }
284
+ interface GezelImportTarget {
285
+ id: string;
286
+ source: 'workspace';
287
+ path: string;
288
+ accept?: string[];
289
+ maxFileBytes?: number;
290
+ writable: boolean;
291
+ reason?: string;
292
+ }
293
+ type GezelImportResult = {
294
+ ok: true;
295
+ name: string;
296
+ file: GezelPageFile;
297
+ } | {
298
+ ok: false;
299
+ name: string;
300
+ error: string;
301
+ };
302
+ interface GezelFileCardOptions {
303
+ file: GezelPageFile;
304
+ variant?: 'tile' | 'row';
305
+ thumbnail?: string | false;
306
+ onActivate?: (file: GezelPageFile) => void | Promise<void>;
307
+ }
308
+ interface GezelFileAdderOptions {
309
+ target: string;
310
+ onAdded?: (files: GezelPageFile[]) => void | Promise<void>;
311
+ }
312
+ interface GezelPageComponent<T> {
313
+ element: HTMLElement;
314
+ update(options: Partial<T>): void;
315
+ destroy(): void;
316
+ }
317
+ interface GezelPageComponents {
318
+ version: 1;
319
+ fileCard(target: string | HTMLElement, options: GezelFileCardOptions): GezelPageComponent<GezelFileCardOptions>;
320
+ fileAdder(target: string | HTMLElement, options: GezelFileAdderOptions): GezelPageComponent<GezelFileAdderOptions> & {
321
+ refresh(): Promise<void>;
322
+ };
323
+ /** Present only in standalone demo mode; releases imported object URLs on reset. */
324
+ demo?: {
325
+ files(): GezelPageFile[];
326
+ reset(): void;
327
+ };
328
+ }
205
329
  /**
206
330
  * The `window.gezel` object a served project-type page codes against.
207
331
  * Installed non-writable before any page script runs; absent entirely in
@@ -214,6 +338,7 @@ interface GezelPageApi {
214
338
  tools: GezelPageToolsApi;
215
339
  /** Read and watch project files within the page's declared scope. */
216
340
  data: GezelPageDataApi;
341
+ tables: GezelPageTablesApi;
217
342
  /** Mirror host UI state (theme). */
218
343
  ui: GezelPageUiApi;
219
344
  /** Ask the host to re-serve the page (embedded); reloads the tab in browser mode. */
@@ -226,4 +351,4 @@ declare global {
226
351
  }
227
352
  }
228
353
 
229
- export { GEZEL_PAGE_API_VERSION, type GezelPageApi, type GezelPageDataApi, type GezelPageDirEntry, type GezelPageError, type GezelPageErrorCode, type GezelPageInfo, type GezelPageMode, type GezelPageReadOptions, type GezelPageReadSource, type GezelPageSourceOptions, type GezelPageTheme, type GezelPageToolReaction, type GezelPageToolResult, type GezelPageToolsApi, type GezelPageUiApi, type GezelPageWatchEvent, type GezelPageWatchOptions };
354
+ export { GEZEL_PAGE_API_VERSION, type GezelFileAdderOptions, type GezelFileCardOptions, type GezelImportResult, type GezelImportTarget, type GezelPageApi, type GezelPageComponent, type GezelPageComponents, type GezelPageDataApi, type GezelPageDirEntry, type GezelPageError, type GezelPageErrorCode, type GezelPageFile, type GezelPageInfo, type GezelPageMode, type GezelPageReadOptions, type GezelPageReadSource, type GezelPageSourceOptions, type GezelPageTable, type GezelPageTableQuery, type GezelPageTableSchema, type GezelPageTablesApi, type GezelPageTheme, type GezelPageToolReaction, type GezelPageToolResult, type GezelPageToolsApi, type GezelPageUiApi, type GezelPageWatchEvent, type GezelPageWatchOptions };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-sdk",
3
- "version": "1.1.7",
3
+ "version": "1.1.8",
4
4
  "description": "SDK for scripts that run in the Gezel sandbox: the gezel object and the defineScript helper.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -63,7 +63,7 @@
63
63
  "!dist/**/*.map"
64
64
  ],
65
65
  "devDependencies": {
66
- "@bendyline/gezel": "1.2.7",
66
+ "@bendyline/gezel": "1.2.8",
67
67
  "tsup": "^8.5.1",
68
68
  "typescript": "^6.0.3",
69
69
  "vitest": "^4.1.10"