@scaleflex/template-builder 0.2.0 → 0.4.1

package/dist/template-builder.d.ts

@@ -1,5 +1,7 @@
 import { LitElement, nothing, type PropertyValues } from 'lit';
-import { type BuilderContentData, type BuilderDirtyData, type BuilderErrorData, type BuilderSaveData, type BuilderTheme } from './protocol';
+import { type CustomMetadataField, type BuilderContentData, type BuilderDirtyData, type BuilderErrorData, type BuilderSaveData, type BuilderTheme } from './protocol';
+import { type StoredTemplate } from './dam-store';
+export type { StoredTemplate, DamStoreAuth } from './dam-store';
 export type TemplateBuilderStatus = 'idle' | 'loading' | 'ready' | 'error';
 /**
  * `save` payload. Which variant arrives follows the mode the element was
@@ -7,9 +9,15 @@ export type TemplateBuilderStatus = 'idle' | 'loading' | 'ready' | 'error';
  * - DAM-backed (default) — `BuilderSaveData`; the app uploaded the template and
  *   reports the resulting `uuid`.
  * - `stateless` — `BuilderContentData`; nothing was stored, and `content` is
- *   the edited template for the host to persist.
+ *   the edited template for the host to persist. With `dam-store` the element
+ *   uploads a rendering copy to Filerobot first, and the detail additionally
+ *   carries `stored` (the copy's uuid + CDN URL) — or `storeError` when that
+ *   copy could not be made; the raw `content` arrives either way.
  */
-export type TemplateBuilderSaveDetail = BuilderSaveData | BuilderContentData | undefined;
+export type TemplateBuilderSaveDetail = BuilderSaveData | (BuilderContentData & {
+    stored?: StoredTemplate;
+    storeError?: string;
+}) | undefined;
 export interface TemplateBuilderEventMap {
     ready: CustomEvent<void>;
     open: CustomEvent<void>;
@@ -119,6 +127,65 @@ export declare class SfxTemplateBuilder extends LitElement {
     brandColor: string;
     /** Colour scheme for the editor chrome. Empty leaves the app's own default. */
     theme: BuilderTheme | '';
+    /**
+     * Metadata model to offer in the editor as the **Custom metadata** value
+     * source: `[{ key, title?, group? }]`. Authors then bind a text variable to
+     * one of your field names instead of to a bare slug.
+     *
+     * Names only — no values travel with the model, and the app resolves nothing
+     * against it. The bound key is stored in the template as `custom_ckey`, and
+     * the variable renders like any free-text one: your pipeline puts
+     * `$slug=value` in the render query. Read the key back from the saved `.fdt`
+     * to know which of your fields each variable expects.
+     *
+     * Leave it empty and the source is not offered at all, so hosts that send
+     * nothing see the editor they always had. Its main use is `sec-template` /
+     * stateless embeds, where the Hub project model — and with it the "File
+     * metadata" source — is unavailable.
+     *
+     * Settable as a property (an array) or as a `custom-metadata` attribute
+     * holding that array as JSON. Neither is trusted to be well-formed:
+     * unparseable JSON is warned about, a value that is not an array is treated as
+     * no model, and individual fields the editor cannot use are dropped there —
+     * a config typo costs the field, not the editor.
+     *
+     * Lit compares by identity: assign a new array to change the model, don't
+     * mutate the one you passed.
+     */
+    customMetadata: CustomMetadataField[];
+    /**
+     * Display name for the custom-metadata value source in the editor's UI.
+     * Empty means the editor's default ("Custom metadata"); a host can rename
+     * it after its own domain — e.g. "External metadata". Pure wording: the
+     * stored template is unaffected.
+     */
+    customMetadataLabel: string;
+    /**
+     * Stateless only: store each save in Filerobot too, so the CDN can render
+     * it. The `save` event then carries `stored: { uuid, url }` next to the raw
+     * `content` — or `storeError` when the copy failed (the raw data arrives
+     * either way; whether that fails the save is the host's call via the ack).
+     * Uses the element's own credentials; a security template needs a scope
+     * that allows uploads.
+     */
+    damStore: boolean;
+    /**
+     * Folder new templates are stored into when `dam-store` is on and the
+     * template id names no existing DAM file (an existing file's own folder
+     * always wins, so same name + folder versions it in place).
+     */
+    storeFolder: string;
+    /**
+     * `dam-store`: the uuid of the rendering copy this document already has —
+     * the `stored.uuid` a previous session's save reported, passed back in by
+     * the host alongside the content. Without it the element only remembers
+     * copies it made itself, so after a reload an unchanged re-save cannot find
+     * its own file and reports a spurious `storeError`, and a changed one starts
+     * a fresh file instead of versioning the existing one. Set it when reopening
+     * a stored template; it belongs to the document, so hosts that swap
+     * documents must swap (or clear) it too — `load()` does this for you.
+     */
+    storedUuid: string;
     /** Ms to wait for the app's ready signal before emitting `error`. 0 disables. */
     readyTimeout: number;
     private _status;
@@ -138,6 +205,21 @@ export declare class SfxTemplateBuilder extends LitElement {
      * back on save.
      */
     private _sentKey?;
+    /**
+     * Identity of the last SAVE the app handed back, in the same shape as
+     * `_sentKey`. A host echoing the full save detail into the props (content,
+     * name, templateQuery) matches this key rather than `_sentKey`, whose name
+     * and query still describe what the template was loaded with — without it
+     * the echo would post a HOST_LOAD that reloads the editor and wipes undo
+     * history on nearly every save (a save almost always changes the query).
+     */
+    private _sentSaveKey?;
+    /**
+     * Identity of the config already delivered, so re-renders don't re-post it.
+     * Undefined means the app has not been told anything yet — set back to that
+     * whenever a new app instance loads.
+     */
+    private _sentConfigKey?;
     /**
      * The `baseUrl` value already reported as unparseable. `_computeSrc()` runs
      * on every update cycle, so without this a bad URL re-emits `error` forever —
@@ -167,11 +249,12 @@ export declare class SfxTemplateBuilder extends LitElement {
      * Stateless mode: load a template, opening the editor if needed. Equivalent
      * to assigning `templateId` / `content` / `templateName` and calling `open()`.
      */
-    load({ content, templateId, name, templateQuery, }: {
+    load({ content, templateId, name, templateQuery, storedUuid, }: {
         content: string;
         templateId?: string;
         name?: string;
         templateQuery?: string;
+        storedUuid?: string;
     }): void;
     /**
      * Stateless mode: open the editor on a new, empty template, opening it if
@@ -219,14 +302,91 @@ export declare class SfxTemplateBuilder extends LitElement {
     private _computeSrc;
     private get _appOrigin();
     private _onMessage;
+    /**
+     * Pending `dam-store` uploads, chained so saves emit in the order the app
+     * posted them. `_storeAndEmitSave` never rejects (its catch emits
+     * `storeError`), so the chain cannot wedge.
+     */
+    private _storeQueue;
+    /**
+     * Saves handed over by the app whose `save` event has not fired yet — the
+     * upload window. Insertion-ordered; membership is what makes a flush and a
+     * completing upload not double-emit the same save.
+     */
+    private _pendingSaves;
+    /**
+     * Identity (id, content, name — not query) of the last document posted to
+     * the app — updated on every ship, and on an accepted save echo (the echoed
+     * document IS the current one; leaving the pre-save key here would make a
+     * later content-request redelivery look like a new document and wipe the
+     * store memory below).
+     */
+    private _lastDocKey?;
+    /**
+     * Monotonic id of the current DOCUMENT. Bumped in exactly one place: when
+     * `_maybeSendContent` ships a genuinely different document (docKey change).
+     * Deliberately NOT bumped on iframe/src changes — a modal close, a theme
+     * swap or an in-place remount is the same document, and treating it as new
+     * forked the file on every such boundary.
+     */
+    private _docEpoch;
+    /**
+     * The copy this element last stored, tagged with the epoch of the document
+     * it belongs to. Written when an upload lands (with the SAVE's epoch, so a
+     * late-landing upload can never masquerade as another document's copy) and
+     * validated at read time — there is no eager reset to get wrong.
+     */
+    private _storeMemory?;
+    /**
+     * Emit every not-yet-emitted `dam-store` save immediately, raw content with
+     * `storeError` in place of the links. Called when waiting any longer risks
+     * the event finding no listener; a still-running upload for a flushed save
+     * is left to finish (the copy usually lands) but will not emit again.
+     *
+     * Public for framework wrappers: one that unsubscribes its listeners before
+     * unmounting must call this first, while they are still attached — the
+     * element's own disconnect-time flush fires only after the wrapper has
+     * stopped listening, and the raw save would be lost. The React wrapper does
+     * this; a vanilla host never needs to call it.
+     */
+    flushPendingSaves(reason?: string): void;
+    private _flushPendingSaves;
+    /**
+     * The `dam-store` save path: upload the edited template to Filerobot, then
+     * emit `save` with the stored copy's links on the detail. The upload is the
+     * render side of the save — the CDN renders only stored files — while the
+     * raw `content` stays the host's copy exactly as without the flag.
+     *
+     * A failed upload still emits `save` (the raw data must reach the host
+     * either way), with `storeError` in place of `stored`; whether a save
+     * without a rendering copy counts as saved is the host's decision, made
+     * where it always is — the save ack.
+     */
+    private _storeAndEmitSave;
     /**
      * Deliver `content` to the app once both sides are ready: it has asked, and
      * we have something new to give it. Skips a re-send of identical content so
      * an unrelated re-render can't discard the user's in-progress edits.
      */
     private _maybeSendContent;
+    /**
+     * Deliver host config to the app. Unlike content this is not requested — the
+     * app has no way to know a host means to send any — so it goes out on the
+     * ready signal and on every later change.
+     *
+     * Sending an empty model is meaningful: it is how a host clears one it set
+     * before. What is skipped is only a *repeat* of what the app already holds,
+     * and the very first send when there was never anything to say.
+     */
+    private _maybeSendConfig;
     /** Identity of a delivered template, as compared against `_sentKey`. */
     private _contentKey;
+    /**
+     * Identity of a save the app handed back — the same shape as
+     * `_contentKey`, but built from the save detail rather than the props, so
+     * a host echoing the detail (whose name/query the save changed) matches.
+     */
+    private _detailKey;
     /** Post into the iframe, targeted at the app origin. False if not mounted. */
     private _postToApp;
     private _startHandshakeTimer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scaleflex/template-builder",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Embeddable web component (<sfx-template-builder>) for the Filerobot design-templates builder",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/dam-store.ts

@@ -0,0 +1,388 @@
+/**
+ * The `dam-store` save path: upload an edited template to Filerobot so the
+ * CDN can render it.
+ *
+ * A stateless save hands the host raw XML — but the CDN renders only stored
+ * files, so a host that wants render URLs (previews, production banners) needs
+ * a copy in the DAM too. With `dam-store` the element makes that copy itself,
+ * with the same multipart upload the DAM-backed editor uses, and the `save`
+ * event carries the stored file's links next to the raw data.
+ *
+ * The raw `content` remains the host's copy of record: nothing here changes
+ * what the save event has always carried.
+ */
+
+import type { BuilderContentData } from './protocol'
+
+export const FILEROBOT_API = 'https://api.filerobot.com'
+
+/** Credentials the element already holds; one of sassKey / secTemplate. */
+export interface DamStoreAuth {
+  token: string
+  sassKey?: string
+  secTemplate?: string
+  sessionUuid?: string
+  companyUuid?: string
+  projectUuid?: string
+}
+
+/** The stored copy's links, carried on the `save` event as `detail.stored`. */
+export interface StoredTemplate {
+  /** DAM file uuid of the stored `.fdt`. */
+  uuid: string
+  /**
+   * CDN URL of the stored file, with its current `?vh=` cache key — append a
+   * template query to render it. Empty when the file record could not be read
+   * back after the upload (the file is stored regardless).
+   */
+  url: string
+}
+
+export interface FileRecord {
+  uuid?: string
+  name?: string
+  folder?: { name?: string }
+  url?: { cdn?: string; public?: string; path?: string }
+}
+
+/**
+ * A security template is not a key — it is exchanged for a short-lived sass
+ * key first, the template authenticating its own exchange. Same call the app
+ * and the asset picker make.
+ *
+ * Exported (with `apiHeaders` / `getFileRecord`) for the demo page, which
+ * plays the host half of the same API conversation — one implementation of
+ * the auth rules, not two drifting copies.
+ */
+export async function resolveKey(auth: DamStoreAuth): Promise<string> {
+  if (!auth.secTemplate) return auth.sassKey ?? ''
+  const res = await fetch(
+    `${FILEROBOT_API}/${encodeURIComponent(auth.token)}/v5/key/${encodeURIComponent(auth.secTemplate)}`,
+    { headers: { 'X-Filerobot-Key': auth.secTemplate } },
+  )
+  const body = (await res.json().catch(() => ({}))) as { key?: string; msg?: string }
+  if (!res.ok || !body.key) {
+    throw new Error(body.msg ?? `key exchange failed: ${res.status}`)
+  }
+  return body.key
+}
+
+/**
+ * Session scope only: a minted key carries its own, and pairing it with a
+ * session's uuids would mix one mode's key with the other mode's scope.
+ */
+export function apiHeaders(auth: DamStoreAuth, key: string): Record<string, string> {
+  const headers: Record<string, string> = { 'X-Filerobot-Key': key }
+  if (!auth.secTemplate) {
+    if (auth.sessionUuid) headers['X-Session-Token'] = auth.sessionUuid
+    if (auth.companyUuid) headers['X-Company-Token'] = auth.companyUuid
+    if (auth.projectUuid) headers['X-Project-Token'] = auth.projectUuid
+  }
+  return headers
+}
+
+/**
+ * Whether a template id plausibly names a DAM file (hex-and-dashes uuid).
+ * Opaque host ids ('demo-1', 'sample-spring-banner') never do — looking them
+ * up would waste a round trip per save and couple every save to whichever
+ * status the API happens to answer a malformed id with.
+ */
+export function looksLikeDamFileUuid(id: string): boolean {
+  return /^[0-9a-f][0-9a-f-]{18,}$/i.test(id)
+}
+
+/**
+ * One file's record. `null` means the identifier names nothing — a 404/gone,
+ * a 4xx rejecting the id itself, or the API's not-found envelope — all normal
+ * answers here. What THROWS is a failure to answer (auth, rate limit, 5xx,
+ * network): collapsing those into null would make a transient blip read as
+ * "file gone", and the callers act on that — re-homing an existing template
+ * into the fallback folder as a duplicate, or failing an unchanged re-save.
+ */
+export async function getFileRecord(
+  auth: DamStoreAuth,
+  key: string,
+  uuid: string,
+): Promise<FileRecord | null> {
+  let res: Response
+  try {
+    res = await fetch(
+      `${FILEROBOT_API}/${encodeURIComponent(auth.token)}/v5/files/${encodeURIComponent(uuid)}`,
+      { headers: apiHeaders(auth, key) },
+    )
+  } catch (err) {
+    throw new Error(
+      `file lookup failed: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+  const body = (await res.json().catch(() => ({}))) as {
+    status?: string
+    msg?: string
+    message?: string
+    file?: FileRecord
+  }
+  // "This identifier names nothing" — not an error worth failing a save for.
+  if ([400, 404, 410, 422].includes(res.status)) return null
+  const message = body.msg ?? body.message ?? ''
+  if (!res.ok || body.status === 'error') {
+    if (/not[ _-]?found|does not exist|no such file/i.test(message)) return null
+    throw new Error(message || `file lookup failed: ${res.status}`)
+  }
+  return body.file ?? null
+}
+
+/**
+ * The newest file with exactly this name in a folder, or null. Used as a last
+ * resort by the unchanged-content conflict path; best-effort by design.
+ */
+async function findByName(
+  auth: DamStoreAuth,
+  key: string,
+  fileName: string,
+  folder: string,
+): Promise<FileRecord | null> {
+  const url = new URL(
+    `${FILEROBOT_API}/${encodeURIComponent(auth.token)}/v5/files`,
+  )
+  url.searchParams.set('q', `name:"${fileName}"`)
+  url.searchParams.set('folder', folder)
+  url.searchParams.set('sort', 'modified_at:desc')
+  url.searchParams.set('limit', '5')
+  const res = await fetch(url, { headers: apiHeaders(auth, key) })
+  const body = (await res.json().catch(() => ({}))) as {
+    status?: string
+    files?: FileRecord[]
+  }
+  if (!res.ok || body.status === 'error') return null
+  return body.files?.find((f) => f.name === fileName) ?? null
+}
+
+/**
+ * FNV-1a 32-bit of the host's template id — the deterministic filename
+ * suffix that keeps one document on one DAM file across page reloads.
+ */
+function hashId(id: string): string {
+  let h = 0x811c9dc5
+  for (let i = 0; i < id.length; i++) {
+    h ^= id.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return (h >>> 0).toString(36)
+}
+
+/** The folder half of a file's URL path (mirrors the app's folderPathFromFile). */
+function folderFromPath(rawPath: string): string {
+  let path: string
+  try {
+    path = decodeURIComponent(rawPath)
+  } catch {
+    path = rawPath
+  }
+  const segments = path.split('/').filter(Boolean)
+  segments.pop()
+  return '/' + segments.join('/')
+}
+
+/**
+ * The `$slug=value` pairs of custom-metadata-bound variables, dropped from the
+ * query stored as the file's `template_query` metadata. The stored default has
+ * to be record-agnostic: the editor hands back whatever values the host opened
+ * it with, and storing those would pin one record's data as the template's own
+ * default. The binding lives in the XML (`custom_ckey`); the value belongs to
+ * the record and goes back in at render time.
+ */
+function stripBoundValues(templateQuery: string, content: string): string {
+  if (!templateQuery) return templateQuery
+  let bound: NodeListOf<Element>
+  try {
+    const doc = new DOMParser().parseFromString(content, 'application/xml')
+    if (doc.querySelector('parsererror')) return templateQuery
+    bound = doc.querySelectorAll(
+      'variable[custom_ckey][source="URL"][type="text_placeholder"]',
+    )
+  } catch {
+    return templateQuery
+  }
+  if (bound.length === 0) return templateQuery
+  const slugs = new Set([...bound].map((el) => el.getAttribute('name') ?? ''))
+  return templateQuery
+    .split('&')
+    .filter(Boolean)
+    .filter((part) => !slugs.has(part.split('=')[0].replace(/^(\$|%24)/, '')))
+    .join('&')
+}
+
+/**
+ * "Content unchanged" — the stored file already IS this save. Filerobot
+ * reports it inconsistently: with a 2xx or an error status alike, at the top
+ * level or inside a per-file `files.failed[]` entry.
+ */
+/** Uniquifies first-save filenames within a page (Date.now can collide). */
+let uploadSeq = 0
+
+const UNCHANGED_UPLOAD_CODES = new Set([
+  'ERROR_SHA1_CONFLICT',
+  'SAME_ASSET_EXISTS_SKIP_UPLOAD',
+])
+
+interface UploadResponseBody {
+  status?: string
+  code?: string
+  msg?: string
+  message?: string
+  file?: FileRecord
+  files?: {
+    uploaded?: FileRecord[]
+    failed?: Array<{ code?: string }>
+  }
+}
+
+/**
+ * Store one save in the DAM and return the stored copy's links.
+ *
+ * Uploads into the folder the file this template is already stored as lives
+ * in — the host's `templateId` when it names a DAM file, else `knownUuid`
+ * (the copy a previous save in this session made; hosts persist `stored.uuid`
+ * rather than echoing it into `template-id`, which would reload the editor) —
+ * so same name + folder makes the backend version the template in place. New
+ * templates land in `fallbackFolder`. Unchanged content resolves to the
+ * already-stored file rather than failing. Throws with a human-readable
+ * message when the copy could not be made; the caller decides what a save
+ * without a stored copy means.
+ */
+export async function storeTemplateInDam(
+  data: BuilderContentData,
+  auth: DamStoreAuth,
+  fallbackFolder: string,
+  knownUuid?: string,
+): Promise<StoredTemplate> {
+  if (!auth.token) throw new Error('dam-store needs a token')
+  const key = await resolveKey(auth)
+  if (!key) throw new Error('dam-store needs a sass key or a security template')
+
+  // Two candidate records with different jobs. The host's `templateId` file
+  // anchors the FOLDER (that is where the template lives) — looked up only
+  // when the id is actually uuid-shaped; an opaque host id names nothing in
+  // the DAM by definition. The copy this session last made (`knownUuid`) is
+  // the freshest row and is what an unchanged-content conflict must resolve
+  // to — under a VERSION policy the `templateId` row can be an older version
+  // whose uuid/`?vh=` would hand the host a regressive pointer.
+  const wantFromId = !!data.templateId && looksLikeDamFileUuid(data.templateId)
+  const wantOwnCopy = !!knownUuid && knownUuid !== data.templateId
+  // Independent lookups — in parallel, not a round trip each. The failure
+  // rules differ by role: the templateId anchor is required (proceeding on a
+  // transient failure would re-home the file into the fallback folder), while
+  // the knownUuid lookup is an optional freshness upgrade whose transient
+  // failure must not fail a save the other anchor can carry — unless it was
+  // the only tie to the existing file.
+  const [fromRes, ownRes] = await Promise.allSettled([
+    wantFromId
+      ? getFileRecord(auth, key, data.templateId as string)
+      : Promise.resolve<FileRecord | null>(null),
+    wantOwnCopy
+      ? getFileRecord(auth, key, knownUuid as string)
+      : Promise.resolve<FileRecord | null>(null),
+  ])
+  if (fromRes.status === 'rejected') throw fromRes.reason
+  const fromId = fromRes.value
+  let ownCopy: FileRecord | null = null
+  if (ownRes.status === 'fulfilled') ownCopy = ownRes.value
+  else if (!fromId) throw ownRes.reason
+
+  const anchor = fromId ?? ownCopy
+  const folder = anchor?.url?.path
+    ? folderFromPath(anchor.url.path)
+    : fallbackFolder || '/'
+
+  // The DAM filename. Versioning-in-place matches on name + folder, so the
+  // name must be STABLE per document and DISTINCT between documents:
+  // - a known copy's own filename wins — versioning keeps matching across
+  //   renames and sessions;
+  // - else, with a host template id, the name carries a hash of that id —
+  //   deterministic, so a reload without the stored-uuid seed still lands on
+  //   the same file, while two "Untitled"s with different ids never collide;
+  // - else (no id at all) a per-page unique suffix — the one case where
+  //   nothing identifies the document across sessions.
+  const display = (data.name ?? '').trim().replace(/\.fdt$/i, '') || 'template'
+  const fileName = anchor?.name
+    ? anchor.name
+    : data.templateId
+      ? `${display}_${hashId(data.templateId)}.fdt`
+      : `${display}_${Date.now().toString(36)}-${++uploadSeq}.fdt`
+
+  const body = new FormData()
+  // The same MIME the app's own template uploads declare
+  // (TEMPLATE_MIME_TYPE in the design-templates-app) — plain text/xml would
+  // risk the copy not being classified as a template_fdt asset.
+  body.append(
+    'files[]',
+    new Blob([data.content], { type: 'text/xml+sfxtemplate' }),
+    fileName,
+  )
+  const storedQuery = stripBoundValues(data.templateQuery ?? '', data.content)
+  if (storedQuery) {
+    body.append(
+      'info[files[]]',
+      JSON.stringify({ custom: { template_query: storedQuery } }),
+    )
+  }
+
+  const res = await fetch(
+    `${FILEROBOT_API}/${encodeURIComponent(auth.token)}/v4/files?folder=${encodeURIComponent(folder)}`,
+    {
+      method: 'POST',
+      headers: { ...apiHeaders(auth, key), 'X-Filerobot-Template': 'true' },
+      body,
+    },
+  )
+  const parsed = (await res.json().catch(() => ({}))) as UploadResponseBody
+
+  const code = parsed.code ?? parsed.files?.failed?.[0]?.code
+  if (code && UNCHANGED_UPLOAD_CODES.has(code)) {
+    let resolved = ownCopy ?? fromId
+    if (!resolved?.uuid) {
+      // No anchor in hand — typically the first save after a page reload
+      // without the stored-uuid seed. In that case the file this conflict
+      // points at is this document's own earlier copy, which carries exactly
+      // the (deterministic) filename we just tried to upload — find it.
+      resolved = await findByName(auth, key, fileName, folder).catch(() => null)
+    }
+    if (resolved?.uuid) {
+      return {
+        uuid: resolved.uuid,
+        url: resolved.url?.cdn ?? resolved.url?.public ?? '',
+      }
+    }
+    // A genuinely foreign copy: the project's dedupe policy already stores
+    // these exact bytes as some other document's file.
+    throw new Error(
+      `this project's deduplication policy already stores this exact content as another file (${code}) — ` +
+        'edit the content, or pass that file\'s uuid as stored-uuid so the save can resolve to it',
+    )
+  }
+  if (!res.ok || parsed.status === 'error') {
+    throw new Error(parsed.msg ?? parsed.message ?? `upload failed: ${res.status}`)
+  }
+
+  const uuid = parsed.file?.uuid ?? parsed.files?.uploaded?.[0]?.uuid
+  if (!uuid) throw new Error('upload succeeded but no file uuid in the response')
+
+  // Read the record back rather than trusting the upload response, whose shape
+  // varies — this is also what yields the fresh `?vh=` cache key. Best-effort:
+  // the file IS stored by now, so a failed read must not turn the save into a
+  // storeError — the url just falls back to what the upload response carried.
+  let record: FileRecord | null = null
+  try {
+    record = await getFileRecord(auth, key, uuid)
+  } catch {
+    // Tolerated — see above.
+  }
+  return {
+    uuid,
+    url:
+      record?.url?.cdn ??
+      record?.url?.public ??
+      parsed.file?.url?.cdn ??
+      '',
+  }
+}

package/src/index.ts

@@ -5,5 +5,7 @@ export {
   type TemplateBuilderStatus,
   type TemplateBuilderEventMap,
   type TemplateBuilderSaveDetail,
+  type StoredTemplate,
+  type DamStoreAuth,
 } from './template-builder'
 export * from './protocol'