@cardinali-studio/adminkit 2.2.24 → 2.2.33

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (C) 2026 Emanuele Cardinali
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# AdminKit
+
+AdminKit is the administration engine we use for small, content-driven websites built with Hugo and deployed on Cloudflare Pages.
+
+It turns a Zod schema into three things that must agree:
+
+- the model edited in the browser;
+- the YAML front matter stored in the repository;
+- the validation performed by the server.
+
+There is no second list of fields hidden in the UI, and no second serializer hidden in a Worker. A field is declared once. The rest of the system reads that declaration.
+
+The package also contains the React administration shell, a media library for R2, Cloudflare Pages Functions, and the persistence primitives used by the D1 publication path.
+
+## The important property
+
+An admin panel should not damage a file merely because it does not understand all of it.
+
+AdminKit preserves the Markdown body, unknown front-matter keys, and their comments. An omitted managed field means “leave it alone”, not “delete it”. Before overwriting an existing file, `checkFidelity()` can prove that reading and writing it again is byte-for-byte stable.
+
+If the codec cannot reproduce a file, it says so. Refusing a save is better than producing plausible-looking YAML with missing data.
+
+## Install
+
+```sh
+npm install @cardinali-studio/adminkit zod
+```
+
+The core codec needs Zod 4. The React application and form exports also use the optional peer dependencies listed in `package.json`; install the ones required by the entry points you use.
+
+The package is ESM-only.
+
+## A complete codec example
+
+Each field has two pieces of metadata:
+
+- `ui` describes how a human edits it;
+- `fm` describes how it lives in the file.
+
+```ts
+import * as z from "zod";
+import {
+  checkFidelity,
+  deserializeItem,
+  fm,
+  serializeItem,
+  ui,
+  yamlStr,
+} from "@cardinali-studio/adminkit";
+
+const Article = {
+  title: z.string().min(1).max(120)
+    .register(ui, {
+      label: "Title",
+      widget: "text",
+      group: "content",
+    })
+    .register(fm, {
+      keys: ["title"],
+      encode: (value) => [`title: ${yamlStr(value)}`],
+      decode: (raw) => String(raw.title ?? ""),
+    }),
+
+  published: z.boolean()
+    .register(ui, {
+      label: "Published",
+      widget: "boolean",
+      group: "visibility",
+    })
+    .register(fm, {
+      keys: ["visible"],
+      encode: (value) => [`visible: ${value === true}`],
+      decode: (raw) => raw.visible === true,
+    }),
+};
+
+const markdown = `---
+# Kept with the field.
+title: "A small page"
+visible: false
+
+# AdminKit does not own this key, so it stays untouched.
+build-note: "keep me"
+---
+The Markdown body stays untouched too.
+`;
+
+if (!checkFidelity(markdown, Article).ok) {
+  throw new Error("This file cannot be edited without loss");
+}
+
+const article = deserializeItem(markdown, Article);
+
+const updated = serializeItem(
+  { ...article, published: true },
+  { shape: Article, oldMd: markdown },
+);
+```
+
+Notice that the model calls the boolean `published` while the file calls it `visible`. That conversion belongs to the schema. Hugo templates, React components, and API handlers should not each invent their own version of it.
+
+### Deleting and retiring fields
+
+Absence is not deletion. To clear a value, pass the empty value understood by its encoder and return no YAML lines.
+
+When a key is obsolete, `retired(schema, keys)` keeps ownership of the old key while emitting nothing. Existing files then lose that key on their next intentional save, without maintaining a separate migration list.
+
+## Mounting the admin application
+
+The application is deliberately mounted as one unit:
+
+```ts
+import { mountAdmin, type SiteAdminConfig } from "@cardinali-studio/adminkit/app";
+import "@cardinali-studio/adminkit/theme.css";
+import "./site-theme.css";
+
+const site: SiteAdminConfig = {
+  // Site identity, page types, schemas, enabled modules and persistence mode.
+  // TypeScript checks the complete contract here.
+};
+
+mountAdmin({
+  site,
+  root: document.querySelector("#root"),
+  storagePrefix: "example-admin",
+});
+```
+
+Import the site's theme after AdminKit's theme. This lets a site replace the CSS custom properties without increasing selector specificity.
+
+`storagePrefix` is part of the site's browser data. Changing it on a live installation silently resets saved media preferences, so migrations should keep the old value.
+
+The shell currently speaks Italian. Content can be monolingual or multilingual; the language of the administration interface is a separate concern.
+
+## Cloudflare Pages Functions
+
+Cloudflare routes Functions by file, while an npm package cannot create files in a consuming project's `functions/` directory. A site therefore keeps two small adapters.
+
+The API catch-all:
+
+```js
+// functions/admin/api/[[path]].js
+import { handleAdminApi } from "@cardinali-studio/adminkit/functions";
+import { serverConfig } from "../../../src/admin/site-config.js";
+
+export function onRequest(context) {
+  return handleAdminApi(context, serverConfig);
+}
+```
+
+And the access middleware:
+
+```js
+// functions/admin/_middleware.js
+export { adminAccess as onRequest } from "@cardinali-studio/adminkit/functions";
+```
+
+Site-specific endpoints may live beside these files. More specific Cloudflare routes take precedence over the catch-all.
+
+The server configuration is site-owned. It supplies schemas, repository details, enabled modules, storage bindings and, in D1 mode, the complete document validator. Missing optional modules fail closed.
+
+## Persistence and publication
+
+The original persistence path writes Markdown through GitHub and lets Hugo build it. The newer path stores immutable revisions in D1 and publishes an exact release snapshot.
+
+The D1 modules are intentionally lower-level than the admin shell. They provide:
+
+- deterministic request checksums and idempotent saves;
+- compare-and-swap protection for concurrent drafts;
+- immutable, checksum-covered release exports;
+- a single deployment lane for code and content;
+- copy-first media moves and delete journals for R2;
+- versioned site-access secrets;
+- pure release materialization, with filesystem effects left to CI.
+
+They do not decide what a site's document means. Validation and materialization remain site-owned.
+
+## Entry points
+
+| Import | Purpose |
+| --- | --- |
+| `@cardinali-studio/adminkit` | Schema registries, front-matter codec, API client, i18n, persistence and release primitives |
+| `@cardinali-studio/adminkit/app` | Complete React administration shell |
+| `@cardinali-studio/adminkit/form` | Schema form and media components |
+| `@cardinali-studio/adminkit/functions` | Cloudflare Pages API router and access middleware |
+| `@cardinali-studio/adminkit/materializer` | Pure release-to-files materialization |
+| `@cardinali-studio/adminkit/preview` | Local preview component |
+| `@cardinali-studio/adminkit/testing` | Content-stability checks for consuming sites |
+| `@cardinali-studio/adminkit/theme.css` | Default design tokens |
+
+## What this is not
+
+AdminKit is not a generic headless CMS, a form builder, or a promise to support every YAML construct.
+
+It is opinionated about the useful narrow case: Hugo content, React 19, Zod 4, Cloudflare Pages, R2 and optionally D1. The front-matter emitter supports the structures used by that system and throws on values it cannot represent safely.
+
+This narrowness is intentional. A smaller system with explicit failure modes is easier to trust around content that people have edited by hand.
+
+## Development
+
+```sh
+npm test
+npm run build
+npm run check
+```
+
+`npm run check` rebuilds the package and runs the Node test suite. The tests include byte-identical codec round trips, malformed-input rejection, import resolution, concurrency conflicts, release invariants, media-operation transitions, and a guard against site-specific code entering the shared package.
+
+Generated files live in `dist/` and are the only application files included in the npm tarball, in addition to npm's standard package metadata and this README.
+
+## License
+
+[0BSD](./LICENSE). Use it, copy it, change it, ship it. Attribution is appreciated but not required.

package/dist/app/app.css

@@ -1216,14 +1216,14 @@ body { margin: 0; background: var(--ak-bg); color: var(--ak-ink); font-family: v
   border-bottom: 1px solid var(--ak-line);
 }
 .dl-cover-head p { margin: 3px 0 0; color: var(--ak-ink-quiet); font-size: 11px; }
-.dl-cover-actions { display: flex; gap: 6px; flex: none; }
-.dl-cover-grid { padding: 14px; display: grid; grid-template-columns: repeat(auto-fill,minmax(116px,1fr)); gap: 8px; }
+.dl-cover-actions { display: flex; flex-wrap: wrap; gap: 6px; flex: none; }
+.dl-cover-grid { padding: 14px; display: grid; grid-template-columns: repeat(auto-fill,minmax(min(150px,100%),1fr)); align-items: start; gap: 10px; }
 .dl-cover-grid button {
   position: relative; min-width: 0; padding: 0; overflow: hidden; cursor: pointer;
   border: 2px solid transparent; border-radius: 6px; background: var(--ak-bg);
 }
 .dl-cover-grid button.is-chosen { border-color: var(--ak-accent); }
-.dl-cover-grid img { width: 100%; aspect-ratio: 3/2; display: block; object-fit: cover; }
+.dl-cover-grid img { width: 100%; height: auto; display: block; object-fit: contain; }
 .dl-cover-grid em {
   position: absolute; top: 5px; right: 5px; width: 18px; height: 18px; display: grid; place-items: center;
   border-radius: 50%; background: var(--ak-accent); color: #fff; font: 600 11px/1 var(--ak-font); font-style: normal;

package/dist/app/delivery.d.ts

@@ -0,0 +1,11 @@
+import "../theme.css";
+import "./app.css";
+import "./next.css";
+export interface DeliveryAdminOptions {
+    name: string;
+    storagePrefix: string;
+    root?: HTMLElement | null;
+    websiteUrl?: string;
+}
+/** Delivery-only entry: no editorial, GitHub, booking or R2 hooks are mounted. */
+export declare function mountDeliveryAdmin(options: DeliveryAdminOptions): void;

package/dist/app/delivery.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StrictMode, useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { setStoragePrefix } from "../index.js";
+import { applyTheme, initialTheme, useTheme } from "./lib/theme.js";
+import { useHashRoute } from "./lib/router.js";
+import { useDeliveries } from "./lib/deliveries.js";
+import { useUploadCompletions } from "./lib/upload-queue.js";
+import { DeliveriesList, DeliveriesTotal, DeliveryWorkspace, NewDeliveryButton } from "./routes/Deliveries.js";
+import { UploadDock } from "./routes/UploadDock.js";
+import "../theme.css";
+import "./app.css";
+import "./next.css";
+/** Delivery-only entry: no editorial, GitHub, booking or R2 hooks are mounted. */
+export function mountDeliveryAdmin(options) {
+    setStoragePrefix(options.storagePrefix);
+    applyTheme(initialTheme());
+    const root = options.root ?? document.getElementById("root");
+    if (!root)
+        throw new Error("adminkit: elemento di montaggio non trovato");
+    createRoot(root).render(_jsx(StrictMode, { children: _jsx(DeliveryAdmin, { ...options }) }));
+}
+function DeliveryAdmin({ name, websiteUrl }) {
+    const [route, go] = useHashRoute();
+    const id = route[0] === "deliveries" ? route[1] : undefined;
+    const api = useDeliveries(id);
+    const { theme, toggle } = useTheme();
+    const completions = useUploadCompletions();
+    const [draftKey, setDraftKey] = useState(0);
+    const [selectedId, setSelectedId] = useState();
+    useEffect(() => { if (completions > 0)
+        void api.load(); }, [completions, api.load]);
+    useEffect(() => {
+        const prevent = (e) => e.preventDefault();
+        window.addEventListener("dragover", prevent);
+        window.addEventListener("drop", prevent);
+        return () => { window.removeEventListener("dragover", prevent); window.removeEventListener("drop", prevent); };
+    }, []);
+    const open = (value) => { setSelectedId(undefined); go(`/deliveries/${value}`); };
+    // Never render the previous transfer while the requested detail is loading.
+    const detail = id && api.detail?.id === id ? api.detail : null;
+    return _jsxs("div", { className: "app", children: [_jsxs("nav", { className: "rail", "aria-label": "Navigazione", children: [_jsxs("div", { className: "rail-brand", children: [_jsx("span", { className: "rail-brand-name", children: name }), _jsx("span", { className: "rail-brand-role", children: "Consegne" })] }), _jsx("button", { className: "rail-item is-on", onClick: () => go("/deliveries"), children: "Transfer" }), _jsxs("div", { className: "rail-foot", children: [websiteUrl && _jsx("a", { className: "rail-item", href: websiteUrl, target: "_blank", rel: "noreferrer", children: "Sito dello studio" }), _jsx("button", { className: "rail-item", onClick: toggle, children: theme === "dark" ? "Tema chiaro" : "Tema scuro" })] })] }), _jsxs("aside", { className: "col", "aria-label": "Elenco transfer", children: [_jsxs("div", { className: "col-head col-head-actions", children: [_jsx("span", { className: "col-title", children: "Transfer" }), _jsx(NewDeliveryButton, { onCreate: () => { setSelectedId(undefined); setDraftKey(v => v + 1); go("/deliveries"); } })] }), _jsx("div", { className: "col-body", children: !api.rows ? _jsx("p", { className: "ak-hint", children: "Carico\u2026" }) : api.rows.length === 0 ? _jsx("p", { className: "ak-hint", children: "Nessun transfer, per ora." })
+                            : _jsx(DeliveriesList, { rows: api.rows, current: id || selectedId, onOpen: open }) }), _jsx("div", { className: "dl-col-foot", children: api.rows && _jsx(DeliveriesTotal, { rows: api.rows }) })] }), _jsx("main", { className: "pane", children: _jsx("div", { className: "pane-body", children: api.error ? _jsxs("div", { role: "alert", children: [_jsx("p", { className: "ak-error", children: api.error }), _jsx("button", { className: "ak-btn", onClick: () => void api.refresh(), children: "Riprova" })] })
+                        : id && !detail ? _jsx("p", { className: "ak-hint", children: "Carico\u2026" })
+                            : _jsx(DeliveryWorkspace, { delivery: detail, busy: api.busy, onAction: api.action, onRefresh: api.refresh, onReload: api.load, onRead: api.read, onDeleted: () => go("/deliveries"), onOpen: open, onSelected: setSelectedId }, id || `new-${draftKey}`) }) }), _jsx(UploadDock, {})] });
+}

package/dist/app/index.d.ts

@@ -1,3 +1,4 @@
+import { type ComponentType } from "react";
 import { type SiteAdminConfig } from "./site.js";
 export type { SiteAdminConfig } from "./site.js";
 export interface MountOptions {
@@ -5,6 +6,8 @@ export interface MountOptions {
     site: SiteAdminConfig;
     /** L'elemento in cui montare. Default: `#root`. */
     root?: HTMLElement | null;
+    /** Site-owned editorial workspace, sharing the kit bootstrap and media library. */
+    workspace?: ComponentType;
     /**
      * Namespace delle preferenze salvate nel browser (ordinamento dei media, ultima cartella
      * aperta nel selettore).
@@ -15,4 +18,4 @@ export interface MountOptions {
      */
     storagePrefix: string;
 }
-export declare function mountAdmin({ site, root, storagePrefix }: MountOptions): void;
+export declare function mountAdmin({ site, root, storagePrefix, workspace }: MountOptions): void;

package/dist/app/index.js

@@ -18,7 +18,7 @@ import { setStoragePrefix } from "../index.js";
 import { App } from "./App.js";
 import { applyTheme, initialTheme } from "./lib/theme.js";
 import { setSiteConfig } from "./site.js";
-export function mountAdmin({ site, root, storagePrefix }) {
+export function mountAdmin({ site, root, storagePrefix, workspace }) {
     setSiteConfig(site);
     setStoragePrefix(storagePrefix);
     /* SINCRONO, prima del render: se il tema lo applicasse solo l'effetto dentro `App`, ci sarebbe
@@ -29,5 +29,6 @@ export function mountAdmin({ site, root, storagePrefix }) {
     const el = root ?? document.getElementById("root");
     if (!el)
         throw new Error("adminkit: elemento di montaggio non trovato (atteso #root)");
-    createRoot(el).render(_jsx(StrictMode, { children: _jsx(App, {}) }));
+    const Workspace = workspace ?? App;
+    createRoot(el).render(_jsx(StrictMode, { children: _jsx(Workspace, {}) }));
 }

package/dist/app/lib/deliveries.d.ts

@@ -7,6 +7,8 @@ export interface DeliverySummary {
     licenseNotes: string;
     ctaEnabled: boolean;
     ctaLabel: string;
+    downloadOriginalsLabel?: string;
+    downloadWebLabel?: string;
     ctaUrl: string;
     expiresAt: string | null;
     filesExpiresAt: string | null;
@@ -21,12 +23,15 @@ export interface DeliverySummary {
     downloadCount: number;
 }
 export interface DeliveryPackage {
+    manifestVersion?: 1 | 2;
+    nextCursor?: number | null;
     id: string;
     deliveryId: string;
     label: string;
     position: number;
     galleryEnabled: boolean;
     webEnabled: boolean;
+    webFormat?: "webp" | "jpg";
     state: "uploading" | "ready" | "failed";
     sourceFingerprint: string;
     fileCount: number;
@@ -37,6 +42,8 @@ export interface DeliveryPackage {
     images: DeliveryPackageImage[];
 }
 export interface DeliveryPackageImage {
+    width?: number;
+    height?: number;
     index: number;
     name: string;
     previewUrl: string;
@@ -72,6 +79,7 @@ export interface DeliveryLink {
     lastDownloadAt: string | null;
 }
 export interface Delivery extends DeliverySummary {
+    canShortenLinks?: boolean;
     packages: DeliveryPackage[];
     links: DeliveryLink[];
     heroes: DeliveryHero[];

package/dist/app/lib/delivery-network.d.ts

@@ -0,0 +1,25 @@
+/** Richieste recuperabili delle consegne. Usare retry solo per operazioni idempotenti. */
+export declare class UploadCancelled extends Error {
+    constructor();
+}
+export interface UploadControl {
+    writerToken?: string;
+    gate(): Promise<void>;
+    signal?: AbortSignal;
+    networkWaiting?(waiting: boolean): void;
+}
+export declare class DeliveryRequestError extends Error {
+    readonly retryable: boolean;
+    readonly retryAfter: number;
+    constructor(message: string, retryable?: boolean, retryAfter?: number);
+}
+export declare function checkCancelled(control?: UploadControl): void;
+export declare function deliveryGate(control?: UploadControl): Promise<void>;
+export declare function waitForRetry(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function retryDelivery<T>(operation: () => Promise<T>, control?: UploadControl, policy?: {
+    maxElapsedMs: number;
+    baseDelayMs: number;
+}): Promise<T>;
+export declare function deliveryJson<T>(url: string, body: Record<string, unknown>, control?: UploadControl, retry?: boolean): Promise<T>;
+/** La callback viene richiamata a ogni tentativo: le firme scadute non vengono riusate. */
+export declare function deliveryPut(sign: () => Promise<string>, body: BodyInit, contentType: string, control?: UploadControl): Promise<string>;

package/dist/app/lib/delivery-network.js

@@ -0,0 +1,159 @@
+/** Richieste recuperabili delle consegne. Usare retry solo per operazioni idempotenti. */
+export class UploadCancelled extends Error {
+    constructor() { super("Caricamento annullato"); this.name = "UploadCancelled"; }
+}
+export class DeliveryRequestError extends Error {
+    retryable;
+    retryAfter;
+    constructor(message, retryable = false, retryAfter = 0) {
+        super(message);
+        this.retryable = retryable;
+        this.retryAfter = retryAfter;
+    }
+}
+export function checkCancelled(control) {
+    if (control?.signal?.aborted)
+        throw new UploadCancelled();
+}
+export async function deliveryGate(control) {
+    checkCancelled(control);
+    if (!control)
+        return;
+    let abort;
+    try {
+        await Promise.race([
+            control.gate(),
+            new Promise((_, reject) => {
+                abort = () => reject(new UploadCancelled());
+                control.signal?.addEventListener("abort", abort, { once: true });
+                if (control.signal?.aborted)
+                    abort();
+            }),
+        ]);
+        checkCancelled(control);
+    }
+    finally {
+        if (abort)
+            control.signal?.removeEventListener("abort", abort);
+    }
+}
+export function waitForRetry(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new UploadCancelled());
+            return;
+        }
+        const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, ms);
+        function abort() { clearTimeout(timer); reject(new UploadCancelled()); }
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+export async function retryDelivery(operation, control, policy = { maxElapsedMs: 30 * 60_000, baseDelayMs: 1000 }) {
+    const started = Date.now();
+    let waiting = false;
+    try {
+        for (let attempt = 0;; attempt++) {
+            checkCancelled(control);
+            await deliveryGate(control);
+            try {
+                const result = await operation();
+                checkCancelled(control);
+                return result;
+            }
+            catch (error) {
+                checkCancelled(control);
+                if (!(error instanceof DeliveryRequestError) || !error.retryable ||
+                    Date.now() - started >= policy.maxElapsedMs)
+                    throw error;
+                if (!waiting) {
+                    waiting = true;
+                    control?.networkWaiting?.(true);
+                }
+                const delay = error.retryAfter || Math.min(30_000, policy.baseDelayMs * 2 ** Math.min(attempt, 5));
+                await waitForRetry(delay + Math.floor(Math.random() * policy.baseDelayMs / 4), control?.signal);
+            }
+        }
+    }
+    finally {
+        if (waiting)
+            control?.networkWaiting?.(false);
+    }
+}
+/** Il timeout comprende anche la lettura della risposta, non solo gli header. */
+async function request(url, init, read, control, timeoutMs = 60_000) {
+    checkCancelled(control);
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    control?.signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(abort, timeoutMs);
+    try {
+        let response;
+        try {
+            response = await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch {
+            checkCancelled(control);
+            throw new DeliveryRequestError("Connessione interrotta. Attendo e riprovo…", true);
+        }
+        return await read(response);
+    }
+    catch (error) {
+        checkCancelled(control);
+        if (controller.signal.aborted)
+            throw new DeliveryRequestError("La richiesta non risponde. Riprovo…", true);
+        if (error instanceof TypeError)
+            throw new DeliveryRequestError("Risposta interrotta. Riprovo…", true);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        control?.signal?.removeEventListener("abort", abort);
+    }
+}
+function httpError(res, message, renewSignature = false) {
+    const transient = [408, 429, 500, 502, 503, 504].includes(res.status) || (renewSignature && res.status === 403);
+    const header = res.headers.get("retry-after");
+    const seconds = Number(header);
+    const retryAfter = header ? (Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - Date.now()) : 0;
+    return new DeliveryRequestError(message || `Richiesta non riuscita (HTTP ${res.status})`, transient, Number.isFinite(retryAfter) ? Math.max(0, Math.min(60_000, retryAfter)) : 0);
+}
+export function deliveryJson(url, body, control, retry = true) {
+    const operation = () => request(url, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(control?.writerToken ? { ...body, writerToken: control.writerToken } : body),
+    }, async (res) => {
+        let value;
+        try {
+            value = await res.json();
+        }
+        catch (error) {
+            if (!res.ok)
+                throw httpError(res);
+            if (error instanceof TypeError || res.headers.get("content-type")?.includes("application/json")) {
+                throw new DeliveryRequestError("La risposta si è interrotta. Riprovo…", true);
+            }
+            throw new DeliveryRequestError("Risposta non valida. Verifica l’accesso al pannello e riprendi il caricamento.");
+        }
+        if (!res.ok || value.ok !== true) {
+            const error = httpError(res, value.error);
+            throw value.retryable === false ? new DeliveryRequestError(error.message) : error;
+        }
+        return value;
+    }, control);
+    return retry ? retryDelivery(operation, control) : operation();
+}
+/** La callback viene richiamata a ogni tentativo: le firme scadute non vengono riusate. */
+export function deliveryPut(sign, body, contentType, control) {
+    return retryDelivery(async () => {
+        const url = await sign();
+        await deliveryGate(control);
+        return request(url, { method: "PUT", body, headers: { "Content-Type": contentType } }, async (res) => {
+            if (!res.ok) {
+                await res.body?.cancel();
+                throw httpError(res, undefined, true);
+            }
+            const etag = res.headers.get("etag") || "";
+            await res.body?.cancel();
+            return etag;
+        }, control, 30 * 60_000);
+    }, control);
+}

package/dist/app/lib/delivery-upload.d.ts

@@ -1,3 +1,5 @@
+import { type UploadControl } from "./delivery-network.js";
+export { UploadCancelled, type UploadControl } from "./delivery-network.js";
 export interface DeliveryUploadProgress {
     phase: "originals" | "derivatives" | "finalizing";
     file: string;
@@ -20,7 +22,7 @@ export interface DeliveryManifestEntry {
     height?: number;
 }
 export interface DeliveryManifest {
-    version: 1;
+    version: 1 | 2;
     createdAt: string;
     entries: DeliveryManifestEntry[];
     skipped: {
@@ -33,9 +35,11 @@ interface ZipMember {
     length: number;
     crc32: number;
 }
-interface UploadOptions {
+export interface UploadOptions {
+    manifestVersion?: 1 | 2;
     galleryEnabled: boolean;
     webEnabled: boolean;
+    webFormat?: "webp" | "jpg";
 }
 interface UploadResult {
     manifest: DeliveryManifest;
@@ -43,28 +47,43 @@ interface UploadResult {
     sourceBytes: number;
     storedBytes: number;
 }
-export interface UploadControl {
-    gate(): Promise<void>;
-}
-export declare class UploadCancelled extends Error {
-    constructor();
+interface MemberCheckpoint {
+    name: string;
+    size: number;
+    read: number;
+    crc: number;
+    chain: string;
+    localOffset: number;
+    dataOffset: number;
+    time: number;
+    date: number;
 }
 export declare function uploadDeliveryPackage(deliveryId: string, packageId: string, selected: File[], options: UploadOptions, onProgress: (progress: DeliveryUploadProgress) => void, control?: UploadControl): Promise<UploadResult>;
 interface ZipSink {
+    gate?(): Promise<void>;
     write(data: Uint8Array): Promise<void>;
     close(): Promise<void>;
 }
 export declare class ZipStream {
+    private utc;
     private sink;
     private offset;
     private entries;
-    constructor(sink: ZipSink);
-    add(nameValue: string, blob: Blob, progress?: (read: number) => void, modified?: Date): Promise<ZipMember>;
+    constructor(sink: ZipSink, utc?: boolean);
+    restore(entries: DeliveryManifestEntry[], files: File[], offset: number): void;
+    add(nameValue: string, blob: Blob, progress?: (read: number) => void, modified?: Date, checkpoint?: (current: MemberCheckpoint, offset: number) => Promise<void>, resume?: MemberCheckpoint): Promise<ZipMember>;
     close(): Promise<void>;
+    private sinkGate;
     private push;
 }
 export declare function setDeliveryRelativePath(file: File, path: string): void;
 export declare function deliveryRelativeName(file: File): string;
+/** Solo metadati: nessuna lettura dei file o richiesta di rete prima del rifiuto. */
+export declare function preflightDeliverySelection(files: File[], options?: UploadOptions): {
+    sourceBytes: number;
+    archiveBytes: number;
+    manifestBytes: number;
+};
 export declare function deliverySelectionName(files: File[]): string;
 export declare function uploadDeliveryHeroObject(deliveryId: string, packageId: string, file: File): Promise<{
     type: "object";
@@ -74,5 +93,4 @@ export declare function uploadDeliveryHeroObject(deliveryId: string, packageId:
     height: number;
     bytes: number;
 }>;
-export declare function deliverySourceFingerprint(files: File[]): Promise<string>;
-export {};
+export declare function deliverySourceFingerprint(files: File[], version?: 1 | 2): Promise<string>;