@bluepic/embed 0.4.0-next.167 → 0.4.0-next.168

package/dist/util/batch/csv.d.ts

@@ -0,0 +1,58 @@
+import { Studio } from '@bluepic/types';
+import type { BatchRow } from './useBatchRows';
+import { type BatchColumnField } from './fields';
+/** The formats a CSV result link can point at, plus the prepopulated editor link. */
+export type BatchCsvFormat = Studio.UrlRenderFormat | 'template-link';
+/** Header of the result column. Stable: re-imports recognise and ignore it. */
+export declare const BATCH_CSV_RESULT_COLUMN = "bluepic_result";
+export interface BatchCsvOptions {
+    format: BatchCsvFormat;
+    /** `https://image.bluepic.io` / `https://image-staging.bluepic.io` (no trailing slash). */
+    urlRenderBaseUrl: string;
+    templateId: string;
+    /** Readable URL form when both are known: `/<orgSlug>/<alias>.<ext>`. */
+    orgSlug?: string;
+    templateAlias?: string | null;
+    /** Multi-canvas: the canvas the editor shows — becomes the extra path segment. */
+    canvasId?: string;
+    /** The editor's own URL without query (`https://template.bluepic.io/<slug>/<templateId>[/<canvas>]`). */
+    templateLinkBaseUrl: string;
+    /** `,` (default) or `;` for spreadsheets in `;` locales. */
+    delimiter?: ',' | ';';
+}
+export interface BatchCsvResult {
+    csv: string;
+    /** The per-row result links, in row order. */
+    links: string[];
+    /** Rows whose URL-render query exceeds the API's byte budget (1-based indices). */
+    overBudget: number[];
+    /** `bluepic_result` header + one binding key per data column. */
+    header: string[];
+}
+/** A binding value as a CSV cell: image objects become their src, other objects JSON. */
+export declare function cellValue(value: unknown): string;
+/** Path of the render URL: alias form when the team + alias are known, else the id form. */
+export declare function urlRenderPath(opts: Pick<BatchCsvOptions, 'templateId' | 'orgSlug' | 'templateAlias' | 'canvasId'>, ext: string): string;
+/** The result link for one row, or null when the format has no link (never happens today). */
+export declare function buildResultLink(row: BatchRow, columns: BatchColumnField[], opts: BatchCsvOptions): {
+    url: string;
+    overBudget: boolean;
+};
+/**
+ * The batch as a spreadsheet: one column per binding key (so a re-import maps
+ * 1:1), image values flattened to their src, and a last column with the
+ * result link per row. UTF-8 with BOM so Excel opens it correctly.
+ */
+export declare function buildBatchCsv(rows: BatchRow[], columns: BatchColumnField[], opts: BatchCsvOptions): BatchCsvResult;
+export interface PrewarmProgress {
+    done: number;
+    total: number;
+    failed: number;
+}
+/**
+ * Request every link once so the render lands in the API's cache (and is
+ * billed) now, not when a recipient first opens the sheet. Videos one at a
+ * time, images four at a time. `no-cors`: we only need the request to happen,
+ * not to read the bytes.
+ */
+export declare function prewarmLinks(links: string[], isVideo: boolean, onProgress?: (progress: PrewarmProgress) => void, signal?: AbortSignal): Promise<PrewarmProgress>;

package/dist/util/batch/export.d.ts

@@ -0,0 +1,77 @@
+import type { Template } from '@bluepic/types';
+import { imageFormats, videoFormats, type RenderRemoteOptions, type RenderRemoteVideoOptions } from '../export';
+import type { BatchRow } from './useBatchRows';
+export type BatchImageFormat = keyof typeof imageFormats;
+export type BatchVideoFormat = keyof typeof videoFormats;
+export type BatchFileFormat = BatchImageFormat | BatchVideoFormat;
+/** How exported files are named: by their 1-based index, or by a Text binding's value. */
+export type BatchNaming = {
+    kind: 'index';
+} | {
+    kind: 'binding';
+    key: string;
+};
+export interface BatchFileExportContext {
+    serial: Template.Serial;
+    campaignId: number;
+    templateId: string;
+    canvasId?: string;
+    /** Template name — the zip name and the index-naming prefix. */
+    name: string;
+    remoteOptions: RenderRemoteOptions;
+    remoteVideoOptions: RenderRemoteVideoOptions;
+    /**
+     * Called once per successfully rendered row with that row's data. The
+     * editor binds it to its per-output credit consumer, so each row is charged
+     * exactly once per session (and never twice for the same content).
+     */
+    consumeOutput: (data: Record<string, unknown>) => Promise<void>;
+    /** Cooperative cancellation: checked before every row starts. */
+    signal?: AbortSignal;
+}
+export interface BatchExportProgress {
+    /** Rows finished (rendered + consumed). */
+    done: number;
+    total: number;
+    /** 0..1 progress inside the row being rendered (videos stream it; images jump). */
+    current: number;
+    /** 1-based index of the row being rendered. */
+    currentIndex: number;
+}
+export interface BatchFileExportResult {
+    /** One blob per exported file (a multi-frame template yields several per row). */
+    files: {
+        name: string;
+        blob: Blob;
+    }[];
+    /** The zip (or the single file) ready to hand out, plus its file name. */
+    output: {
+        blob: Blob;
+        fileName: string;
+    };
+    cancelled: boolean;
+}
+/** Image rows render four at a time, videos strictly one after the other (decision 2026-09-02). */
+export declare const BATCH_IMAGE_CONCURRENCY = 4;
+export declare const BATCH_VIDEO_CONCURRENCY = 1;
+/** A file-system-safe base name from a binding value; empty when nothing usable remains. */
+export declare function sanitizeFileName(value: unknown): string;
+/** Base names for every row, unique (`name`, `name_2`, `name_3`, …). */
+export declare function batchFileBaseNames(rows: BatchRow[], naming: BatchNaming, prefix: string): string[];
+/**
+ * Render every row server-side and pack the results.
+ *
+ * Images go through the campaign render endpoint (which does not charge — the
+ * per-row `consumeOutput` does), videos through the video render service.
+ * Rows are rendered in order; a failed row aborts the export with its error
+ * so nothing half-billed slips through silently.
+ */
+export declare function exportBatchFiles(rows: BatchRow[], format: BatchFileFormat, naming: BatchNaming, ctx: BatchFileExportContext, onProgress?: (progress: BatchExportProgress) => void): Promise<BatchFileExportResult>;
+/** One file stays a file; several become a zip named after the template. */
+export declare function packFiles(files: {
+    name: string;
+    blob: Blob;
+}[], zipBaseName: string): Promise<{
+    blob: Blob;
+    fileName: string;
+}>;

package/dist/util/batch/fields.d.ts

@@ -0,0 +1,22 @@
+import type { BluepicField, Template } from '@bluepic/types';
+/** A field as a batch-table column: the field plus where it came from. */
+export interface BatchColumnField {
+    field: BluepicField;
+    /** Stable key for the column (the field's first binding, else its index path). */
+    key: string;
+    /** Group breadcrumb the field lives in, for the header caption. */
+    groupPath: string[];
+    /** 1-based slide the field belongs to on multi-slide templates, else undefined. */
+    slide?: number;
+}
+/**
+ * Every value-bearing field of a serial as a flat column list. Groups are
+ * flattened (their children become columns, the group's description is kept
+ * as a breadcrumb); instructions are dropped.
+ */
+export declare function flattenBatchFields(serial: Template.Serial | undefined): BatchColumnField[];
+/** The binding keys a field writes, in model order. */
+export declare function bindingKeysOf(field: BluepicField): string[];
+export declare function isImageField(field: BluepicField): boolean;
+/** A Text binding a file name / CSV column can be derived from. */
+export declare function isTextField(field: BluepicField): boolean;

package/dist/util/batch/parseCSV.d.ts

@@ -0,0 +1,72 @@
+export type LocaleConfig = 'de' | 'en' | 'auto';
+export type CSVDelimiter = ',' | ';' | 'auto';
+type StringDescriptor = {
+    type: 'string';
+    value: string;
+};
+type NumberDescriptor = {
+    type: 'number';
+    value: number;
+    unit?: string;
+};
+type BooleanDescriptor = {
+    type: 'boolean';
+    value: boolean;
+};
+type DateDescriptor = {
+    type: 'date';
+    value: Date;
+    format: string;
+};
+type URLDescriptor = {
+    type: 'url';
+    value: string;
+    protocol: string;
+};
+type ColorDescriptor = {
+    type: 'color';
+    value: string;
+    rgb: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    hex: string;
+    hsl: {
+        h: number;
+        s: number;
+        l: number;
+    };
+    alpha: number;
+    format: 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'name' | 'keyword';
+};
+type JSONObjectDescriptor = {
+    type: 'json-object';
+    value: Record<string, unknown>;
+};
+type JSONArrayDescriptor = {
+    type: 'json-array';
+    value: unknown[];
+};
+type NullDescriptor = {
+    type: 'null';
+    value: null;
+};
+export type CellDescriptor = StringDescriptor | NumberDescriptor | BooleanDescriptor | DateDescriptor | URLDescriptor | ColorDescriptor | JSONObjectDescriptor | JSONArrayDescriptor | NullDescriptor;
+export type InferredTable = CellDescriptor[][];
+export declare function isString(cell: CellDescriptor): cell is StringDescriptor;
+export declare function isNumber(cell: CellDescriptor): cell is NumberDescriptor;
+export declare function isBoolean(cell: CellDescriptor): cell is BooleanDescriptor;
+export declare function isDate(cell: CellDescriptor): cell is DateDescriptor;
+export declare function isURL(cell: CellDescriptor): cell is URLDescriptor;
+export declare function isColor(cell: CellDescriptor): cell is ColorDescriptor;
+export declare function isJSONObject(cell: CellDescriptor): cell is JSONObjectDescriptor;
+export declare function isJSONArray(cell: CellDescriptor): cell is JSONArrayDescriptor;
+export declare function isNull(cell: CellDescriptor): cell is NullDescriptor;
+export declare function exampleUsage(inferredTable: InferredTable): void;
+export declare function inferredCellToString(cell: CellDescriptor): string;
+export declare function heuristicInferTable(rawTable: string[][], locale: LocaleConfig): InferredTable;
+export declare function detectCSVDelimiter(raw: string): ',' | ';';
+export declare function parseCSVRaw(raw: string, delimiter?: ',' | ';'): string[][];
+export declare function parseCSV(raw: string, locale: LocaleConfig, delimiter?: CSVDelimiter): InferredTable;
+export {};

package/dist/util/batch/useBatchRows.d.ts

@@ -0,0 +1,67 @@
+import { type Ref } from 'vue';
+/**
+ * Batch editor data model.
+ *
+ * A row is one set of binding values — exactly the object the live template
+ * and the renderer consume as `data` — plus a stable id. Ids (not indices) are
+ * what selection and the active row point at, so deleting or reordering rows
+ * never shifts the meaning of "row 3 is selected".
+ */
+export interface BatchRow {
+    id: string;
+    data: Record<string, unknown>;
+}
+/** Hard cap on rows per batch (decision 2026-09-02). */
+export declare const BATCH_MAX_ROWS = 1024;
+export interface UseBatchRowsOptions {
+    /** The bindings every row starts from (`serial.bindings`). */
+    seed: () => Record<string, unknown>;
+    /**
+     * sessionStorage key. Rows survive a reload / a canvas switch (the editor
+     * re-mounts per canvas) under it. Undefined = no persistence.
+     */
+    storageKey: Ref<string | undefined>;
+    /** Rows the host hands in (`v-model:batchRows`); take precedence over storage. */
+    initial?: BatchRow[];
+}
+export declare function useBatchRows(opts: UseBatchRowsOptions): {
+    rows: Ref<{
+        id: string;
+        data: Record<string, unknown>;
+    }[], BatchRow[] | {
+        id: string;
+        data: Record<string, unknown>;
+    }[]>;
+    activeRowId: Ref<string, string>;
+    activeIndex: import("vue").ComputedRef<number>;
+    activeRow: import("vue").ComputedRef<{
+        id: string;
+        data: Record<string, unknown>;
+    }>;
+    selectedIds: Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>;
+    selectedRows: import("vue").ComputedRef<{
+        id: string;
+        data: Record<string, unknown>;
+    }[]>;
+    targetRows: import("vue").ComputedRef<{
+        id: string;
+        data: Record<string, unknown>;
+    }[]>;
+    allSelected: import("vue").ComputedRef<boolean>;
+    atCapacity: import("vue").ComputedRef<boolean>;
+    setActive: (id: string) => void;
+    activateOffset: (delta: number) => void;
+    addRow: (sourceId?: string) => BatchRow | undefined;
+    removeRows: (ids: string[]) => void;
+    moveRow: (id: string, delta: -1 | 1) => void;
+    toggleSelected: (id: string, on?: boolean) => void;
+    selectAll: (on: boolean) => void;
+    ensureRowsFrom: (fromIndex: number, count: number) => BatchRow[];
+    importRows: (datasets: Record<string, unknown>[], mode: "append" | "replace") => {
+        imported: number;
+        dropped: number;
+    };
+    replaceAll: (next: BatchRow[]) => void;
+    makeRow: (data?: Record<string, unknown>) => BatchRow;
+};
+export type BatchRowsModel = ReturnType<typeof useBatchRows>;

package/dist/util/export.d.ts

@@ -78,6 +78,9 @@ campaignCaption?: Ref<string | undefined>,
  */
 canvasId?: Ref<string | undefined>): {
     triggerExport: () => Promise<void>;
+    consumeOutputFor: (rowData: {
+        [k: string]: unknown;
+    }) => Promise<void>;
     preCacheLocalRender: () => Promise<void>;
     rendering: Ref<boolean, boolean>;
     videoRenderingProgress: Ref<number | undefined, number | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluepic/embed",
-  "version": "0.4.0-next.167",
+  "version": "0.4.0-next.168",
   "description": "Bluepic embed sdk",
   "type": "module",
   "sideEffects": false,