@holistics/anfra-sdk 0.7.1 → 0.8.0

package/dist/{types-BlzJVcUl.d.ts → types-IR4TNw-M.d.ts}

@@ -86,6 +86,19 @@ interface User {
  */
 interface SdkFeatures {
     dateDrill?: boolean;
+    /**
+     * Whether the host can export a query's result (`query.export()`): its Backend has
+     * `exportQuery`. `mountDataApp` says so for every frame; `createSdk` reads it off the Backend
+     * when the host does not. An author shows an export button when this and
+     * `user.permissions.canExportData` are both true.
+     */
+    export?: boolean;
+    /**
+     * Whether `Anfra.render()` can save a rendering here: the host turned it on
+     * (`mountDataApp({ render: true })`). An author shows a render button when this and
+     * `user.permissions.canExportData` are both true.
+     */
+    render?: boolean;
 }
 interface SdkEnvironment {
     datasets: Record<string, DatasetDescriptor>;
@@ -94,6 +107,37 @@ interface SdkEnvironment {
     backend: Backend;
     /** Absent means the host did not say, and nothing is blocked; only an explicit `false` throws. */
     features?: SdkFeatures;
+    /** Draws and saves a rendering: given by the frame bootstrap, which can reach the page and the host. */
+    render?: (request: RenderRequest) => Promise<Rendering>;
+}
+/** A rendering's file format. A PDF is one page the size of the rendering. */
+type RenderFormat = 'png' | 'pdf';
+/**
+ * What to render, and how. `block` or `container` names one node of the structure by its id;
+ * neither renders the whole app.
+ */
+interface RenderRequest {
+    block?: string;
+    container?: string;
+    format: RenderFormat;
+    /** The file's name, with the format's extension added when it has none. */
+    filename?: string;
+    /** Device pixels per CSS pixel. Defaults to the screen's, at least 2, lowered to fit a canvas. */
+    pixelRatio?: number;
+}
+/** A picture of the app, or of one node, as the reader saw it: saved for them, and handed back. */
+interface Rendering {
+    filename: string;
+    format: RenderFormat;
+    /** In CSS pixels: what was drawn, before `pixelRatio`. */
+    width: number;
+    height: number;
+    blob: Blob;
+    /**
+     * Images left blank in the picture, by URL: their servers send no CORS headers, so the browser
+     * won't let them be drawn. Their space is kept. Empty when nothing was left out.
+     */
+    omitted: string[];
 }
 type ConditionValue = string | number | boolean;
 /**
@@ -522,6 +566,57 @@ interface BackendQueryResult {
     };
     debug?: QueryDebug;
 }
+/** A file format an export can be written in. CSV is the only one yet; a server may add more. */
+type ExportFormat = 'csv' | (string & {});
+/** A format's options. Each applies to the formats it names; the server refuses one given to another. */
+interface ExportFormatOptions {
+    /** csv: the header row: the columns' labels (the default), their names, or none. */
+    header?: 'labels' | 'names' | 'none';
+    /** csv: start the file with a UTF-8 byte-order mark, which Excel needs to read non-ASCII text. */
+    bom?: boolean;
+}
+/** What `query.export()` takes. Every field is optional. */
+interface ExportOptions {
+    /**
+     * The file's name, with the format's extension added when it has none. Defaults to the app's
+     * title and the query's name (`Sales - revenueByMonth.csv`), or the query's name alone.
+     */
+    filename?: string;
+    /** `csv` unless given. */
+    format?: ExportFormat;
+    /** For CSV, `bom` defaults to `true`: a person opens what a Data App exports. */
+    formatOptions?: ExportFormatOptions;
+    /** Cancels the export. `query.abort()` does not: an export is not the query's run. */
+    signal?: AbortSignal;
+}
+/**
+ * A query's whole result as a file: what the Backend made, and the host has already started
+ * saving for the reader. `url` works with a plain `GET` until `expiresAt`.
+ */
+interface ExportResult {
+    url: string;
+    filename: string;
+    format: ExportFormat;
+    /** The rows the file holds. */
+    rowCount: number;
+    expiresAt: Date;
+}
+/**
+ * An export: the same query a run sends, built by the same code so the two cannot drift, but with
+ * no page (an export is every row) and no cache to bust; plus the file's format and name.
+ */
+interface BackendExportRequest {
+    /** The dataset's `name`, as in `DatasetDescriptor.name`. */
+    dataset: string;
+    /** The query's AQL, verbatim. */
+    aql: string;
+    input: QueryInput;
+    /** Absent when the app declares none, leaving the backend's default. */
+    timezone?: string;
+    format?: ExportFormat;
+    formatOptions?: ExportFormatOptions;
+    filename?: string;
+}
 interface FieldSuggestionsRequest {
     /** The dataset's `name`. */
     dataset: string;
@@ -540,6 +635,11 @@ interface FieldSuggestionsRequest {
 interface Backend {
     submitQuery(request: BackendQueryRequest, signal: AbortSignal): Promise<BackendQueryResult>;
     fieldSuggestions(request: FieldSuggestionsRequest, signal: AbortSignal): Promise<ConditionValue[]>;
+    /**
+     * Export a query's whole result as a file, and answer its link once the file is ready. Optional:
+     * a host that cannot export leaves it out, and `query.export()` rejects with a `TransportError`.
+     */
+    exportQuery?(request: BackendExportRequest, signal: AbortSignal): Promise<ExportResult>;
 }
 
-export { type StructureKind as $, type Aggregation as A, type Backend as B, type ColumnMeta as C, type DatasetDescriptor as D, type EntityKind as E, FILTER_AGGREGATIONS as F, type InspectedQuery as G, type InspectedSelection as H, type InspectedApp as I, type InspectedStructure as J, type LocateKind as K, type Listener as L, type LocateTarget as M, type MappingJson as N, type Operator as O, type QueryDeclaration as P, type QueryDebug as Q, type QueryInput as R, type QueryResult as S, type QuerySort as T, type QueryState as U, type Row as V, type SdkEnvironment as W, type SdkFeatures as X, type Selection as Y, type SelectionCondition as Z, type SemanticType as _, type AppDeclaration as a, type StructureNode as a0, type Unsubscribe as a1, type User as a2, type AppJson as b, type ArrowType as c, type BackendCondition as d, type BackendDateDrill as e, type BackendFilter as f, type BackendQueryRequest as g, type BackendQueryResult as h, type BackendSort as i, type Condition as j, type ConditionValue as k, type ControlMappingJson as l, type CrossFilterJson as m, type DateDrillDeclaration as n, type DateGrain as o, type DateTransformation as p, type EntityRef as q, type EntityUsage as r, type ExecuteOptions as s, type ExecuteSummary as t, type FieldSuggestionsRequest as u, type FilterAggregation as v, type FilterDeclaration as w, type FilterValueType as x, type InspectedControl as y, type InspectedError as z };
+export { type RenderRequest as $, type Aggregation as A, type Backend as B, type ColumnMeta as C, type DatasetDescriptor as D, type EntityKind as E, FILTER_AGGREGATIONS as F, type FilterAggregation as G, type FilterDeclaration as H, type FilterValueType as I, type InspectedApp as J, type InspectedControl as K, type InspectedError as L, type InspectedQuery as M, type InspectedSelection as N, type InspectedStructure as O, type Listener as P, type LocateKind as Q, type LocateTarget as R, type MappingJson as S, type Operator as T, type QueryDebug as U, type QueryDeclaration as V, type QueryInput as W, type QueryResult as X, type QuerySort as Y, type QueryState as Z, type RenderFormat as _, type AppDeclaration as a, type Rendering as a0, type Row as a1, type SdkEnvironment as a2, type SdkFeatures as a3, type Selection as a4, type SelectionCondition as a5, type SemanticType as a6, type StructureKind as a7, type StructureNode as a8, type Unsubscribe as a9, type User as aa, type AppJson as b, type ArrowType as c, type BackendCondition as d, type BackendDateDrill as e, type BackendExportRequest as f, type BackendFilter as g, type BackendQueryRequest as h, type BackendQueryResult as i, type BackendSort as j, type Condition as k, type ConditionValue as l, type ControlMappingJson as m, type CrossFilterJson as n, type DateDrillDeclaration as o, type DateGrain as p, type DateTransformation as q, type EntityRef as r, type EntityUsage as s, type ExecuteOptions as t, type ExecuteSummary as u, type ExportFormat as v, type ExportFormatOptions as w, type ExportOptions as x, type ExportResult as y, type FieldSuggestionsRequest as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holistics/anfra-sdk",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Data Apps on anfra: the authoring layer (app), what hosts one (host), the core API client (api), and their shared contract (common)",
   "license": "Apache-2.0",
   "repository": {
@@ -51,6 +51,7 @@
   "devDependencies": {
     "@types/node": "^22.20.4",
     "esbuild": "^0.28.2",
+    "html-to-image": "1.11.13",
     "jsdom": "^26.1.0",
     "openapi-typescript": "^7.13.0",
     "tsup": "^8.5.1",

package/dist/chunk-PKBMQBKP.js

@@ -1,7 +0,0 @@
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-
-export {
-  __publicField
-};