import { mimeFor } from '../util/mime.js'; /** * Image (and other binary) files a theme ships with its content * (`theme.json` → `assets[]`). * * A widget setting holds a URL, so a theme that wants to ship a banner has * historically had two bad options: reference a file in its own `public/` * folder (renders through the image processor's theme fallback, but the file is * never in the store's media storage — invisible to the file browser, local * even when the store is on S3, and dead the moment the theme changes), or ship * no image at all. `assets[]` closes that: the file travels with the theme, * `theme:active` uploads it through the configured storage provider, and the * settings that referenced it are rewritten to the URL the upload returned. * * A setting refers to an asset by TOKEN, never by URL: * * "image": "theme-asset:demo/hero.jpg" * * The token is what the manifest and the install snapshot carry, so it is * stable across stores and across storage providers. Resolution to a real URL * happens in memory, on both sides of the three-way diff, which is what keeps * an upgrade from reading as "the author changed this image" (see * `resolveAssetTokens`). */ /** * Declared files live in the theme's existing `public/` folder — deliberately * not a second asset directory. A declared file therefore stays reachable the * way it always was (the theme serves `public/` at the URL root, and * `imageProcessor.ts` falls back to it for an `/assets/` path) AND is uploaded * into the store's storage. The token in a setting decides which one is used. */ export declare const THEME_ASSETS_DIR = "public"; /** `theme-asset:` — the reference a widget setting carries. */ export declare const ASSET_TOKEN_PREFIX = "theme-asset:"; export interface AssetRecord { /** Path relative to `themes//public/`, e.g. `demo/hero.jpg`. Also the asset's identity. */ path: string; } export interface UploadedAsset { path: string; url: string; } /** The upload seam, injected so install stays testable and `lib/` stays free of a hard cms import. */ export type AssetUploader = (files: { filename: string; buffer: Buffer; mimetype: string; size: number; }[], destinationPath: string) => Promise<{ name: string; url: string; }[]>; export declare function assetToken(assetPath: string): string; /** * Is `p` a safe theme-relative asset path? Rejects absolute paths, `..` * traversal, backslashes and empty segments — a manifest is data, and it * decides which files the installer reads off disk. */ export declare function isSafeAssetPath(p: unknown): p is string; /** Every `theme-asset:` token appearing anywhere in a value tree. */ export declare function collectAssetTokens(value: unknown): Set; /** * Replace every `theme-asset:` with its uploaded URL, deeply, returning a * new value. A token with no entry in `urls` is left as it is: the diff then * sees the same unresolved string on both sides, so an asset that failed to * upload cannot silently turn into a broken URL in the database. */ export declare function resolveAssetTokens(value: T, urls: Map): T; /** Where an asset lands in storage: `theme//`, filename kept. */ export declare function assetDestination(themeId: string, assetPath: string): { destination: string; filename: string; }; export { mimeFor }; export declare function assetContentHash(buffer: Buffer): string; export interface UploadThemeAssetsResult { urls: Map; uploaded: UploadedAsset[]; missing: string[]; } /** * Upload every declared asset through the store's configured storage provider * and return the token → URL map the manifest is resolved with. * * Uploads are by path, so re-running activation overwrites the same key rather * than accumulating copies. A file that is declared but absent from the theme * is reported in `missing` and left unresolved — the caller decides whether * that is fatal. */ export declare function uploadThemeAssets(themeDir: string, themeId: string, assets: AssetRecord[], upload: AssetUploader): Promise;