@aglyn/aglyn 1.0.0-beta.288 → 1.0.0-beta.290

package/src/lib/app-utils/visitor-upload.js

@@ -0,0 +1,312 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*==========================================
+ * FILES A VISITOR SENDS A BUSINESS (AGL-4096).
+ *
+ * Artwork for a quote, a logo with a request form: files someone without an
+ * account hands a business through its site. This module is the policy, pure
+ * and shared by the browser and the server:
+ *
+ * - which files are taken ({@link VISITOR_UPLOAD_TYPES}: PNG, JPEG, WebP,
+ *   GIF, PDF, SVG, AI, EPS, PSD, TIFF), how big ({@link VISITOR_UPLOAD_MAX_BYTES})
+ *   and how many at once ({@link VISITOR_UPLOAD_MAX_FILES});
+ * - what a file's type IS ({@link resolveVisitorUploadType}): read from its
+ *   name and checked against what the browser said, so a `.psd` a browser
+ *   labels `application/octet-stream` is still a Photoshop file and a `.png`
+ *   labelled `text/html` is nothing;
+ * - where its bytes live ({@link visitorUploadPendingPath} while it is on its
+ *   way, {@link visitorUploadFinalPath} once it is checked);
+ * - the record a finished upload is ({@link VisitorUploadFile}).
+ *
+ * The server half (`@aglyn/tenant-data-admin/server/visitor-upload`) signs the
+ * upload, inspects the bytes and moves them; the browser half
+ * (`visitor-upload-client.ts`) sends them. A plugin that takes files (commerce
+ * for a quote's artwork, forms for a request) names its own `purpose` and the
+ * record it is for, and decides for itself who may upload for it.
+ *=========================================*/ /** The most one file may weigh. */ export const VISITOR_UPLOAD_MAX_BYTES = 25 * 1024 * 1024;
+/** The most files one submission carries. */ export const VISITOR_UPLOAD_MAX_FILES = 10;
+/** How long the signed upload a ticket carries can be used, from its minting. */ export const VISITOR_UPLOAD_TICKET_TTL_MS = 15 * 60 * 1000;
+/**
+ * Where uploads wait until they are checked. Top-level, never under `hosts/`:
+ * the bucket's lifecycle deletes whatever is still here a day after it
+ * arrived (`cloud/media-bucket-lifecycle.json`), which no rule may do under a
+ * prefix that holds live customer files.
+ */ export const VISITOR_UPLOAD_PENDING_PREFIX = 'visitor-uploads-pending/';
+/** The honeypot field a form posts beside its files, as the forms plugin names it. */ export const VISITOR_UPLOAD_HONEYPOT_FIELD = 'website';
+export const VISITOR_UPLOAD_TYPES = [
+    {
+        contentType: 'image/png',
+        extensions: [
+            '.png'
+        ],
+        label: 'PNG',
+        inline: true
+    },
+    {
+        contentType: 'image/jpeg',
+        extensions: [
+            '.jpg',
+            '.jpeg'
+        ],
+        label: 'JPEG',
+        inline: true,
+        aliases: [
+            'image/jpg',
+            'image/pjpeg'
+        ]
+    },
+    {
+        contentType: 'image/webp',
+        extensions: [
+            '.webp'
+        ],
+        label: 'WebP',
+        inline: true
+    },
+    {
+        contentType: 'image/gif',
+        extensions: [
+            '.gif'
+        ],
+        label: 'GIF',
+        inline: true
+    },
+    {
+        contentType: 'application/pdf',
+        extensions: [
+            '.pdf'
+        ],
+        label: 'PDF',
+        inline: false,
+        aliases: [
+            'application/x-pdf'
+        ]
+    },
+    // Stripped of script on the way in, and still downloaded rather than drawn.
+    {
+        contentType: 'image/svg+xml',
+        extensions: [
+            '.svg'
+        ],
+        label: 'SVG',
+        inline: false
+    },
+    {
+        contentType: 'application/illustrator',
+        extensions: [
+            '.ai'
+        ],
+        label: 'AI',
+        inline: false,
+        aliases: [
+            'application/postscript',
+            'application/pdf',
+            'application/vnd.adobe.illustrator'
+        ]
+    },
+    {
+        contentType: 'application/postscript',
+        extensions: [
+            '.eps'
+        ],
+        label: 'EPS',
+        inline: false,
+        aliases: [
+            'application/eps',
+            'image/eps',
+            'image/x-eps',
+            'application/x-eps'
+        ]
+    },
+    {
+        contentType: 'image/vnd.adobe.photoshop',
+        extensions: [
+            '.psd'
+        ],
+        label: 'PSD',
+        inline: false,
+        aliases: [
+            'application/x-photoshop',
+            'application/photoshop',
+            'application/psd',
+            'image/psd',
+            'image/x-photoshop'
+        ]
+    },
+    {
+        contentType: 'image/tiff',
+        extensions: [
+            '.tif',
+            '.tiff'
+        ],
+        label: 'TIFF',
+        inline: false,
+        aliases: [
+            'image/x-tiff'
+        ]
+    }
+];
+/** Types a browser sends when it does not know; the name decides then. */ const UNKNOWN_TYPES = new Set([
+    '',
+    'application/octet-stream',
+    'binary/octet-stream',
+    'application/unknown'
+]);
+/** `PNG, JPEG, WebP, GIF, PDF, SVG, AI, EPS, PSD or TIFF`. */ export function describeVisitorUploadTypes() {
+    const labels = VISITOR_UPLOAD_TYPES.map((type)=>type.label);
+    return `${labels.slice(0, -1).join(', ')} or ${labels[labels.length - 1]}`;
+}
+/** The file picker's `accept`: every extension and type taken. */ export const VISITOR_UPLOAD_ACCEPT = VISITOR_UPLOAD_TYPES.flatMap((type)=>[
+        ...type.extensions,
+        type.contentType
+    ]).join(',');
+/** `25 MB`. */ export function formatVisitorUploadBytes(bytes) {
+    if (!(bytes > 0)) return '0 KB';
+    if (bytes < 1024 * 1024) return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+    const mb = bytes / (1024 * 1024);
+    return `${mb >= 10 ? Math.round(mb) : Math.round(mb * 10) / 10} MB`;
+}
+/** The extension of a file name, lower-case with its dot, or ''. */ function extensionOf(name) {
+    const dot = name.lastIndexOf('.');
+    return dot > 0 ? name.slice(dot).toLowerCase() : '';
+}
+/**
+ * The type a file is taken as, or null when it is not one this takes. The
+ * NAME decides, because a browser reports most design files as nothing or as
+ * something generic; the reported type only has to agree with it (be this
+ * type, one it is known by, or unknown). The bytes are checked against the
+ * answer after they arrive.
+ */ export function resolveVisitorUploadType(name, reportedType) {
+    var _byName_aliases;
+    const extension = extensionOf(String(name != null ? name : ''));
+    const reported = String(reportedType != null ? reportedType : '').split(';')[0].trim().toLowerCase();
+    const byName = VISITOR_UPLOAD_TYPES.find((type)=>type.extensions.includes(extension));
+    if (!byName) return null;
+    if (UNKNOWN_TYPES.has(reported) || reported === byName.contentType) return byName;
+    return ((_byName_aliases = byName.aliases) == null ? void 0 : _byName_aliases.includes(reported)) ? byName : null;
+}
+/** A stored type, as the list of types knows it; null for anything else. */ export function visitorUploadTypeOf(contentType) {
+    var _VISITOR_UPLOAD_TYPES_find;
+    return (_VISITOR_UPLOAD_TYPES_find = VISITOR_UPLOAD_TYPES.find((type)=>type.contentType === contentType)) != null ? _VISITOR_UPLOAD_TYPES_find : null;
+}
+/** Whether a stored file may be shown as a picture rather than downloaded. */ export function visitorUploadIsInline(contentType) {
+    var _visitorUploadTypeOf;
+    return ((_visitorUploadTypeOf = visitorUploadTypeOf(contentType)) == null ? void 0 : _visitorUploadTypeOf.inline) === true;
+}
+/**
+ * A file name safe to keep and to put in a download's header: no folders, no
+ * control or quoting characters, at most 120 characters, and ending in the
+ * extension of the type it was taken as.
+ */ export function safeVisitorUploadName(name, type) {
+    var _String_split_pop;
+    const last = (_String_split_pop = String(name != null ? name : '').split(/[\\/]/).pop()) != null ? _String_split_pop : '';
+    // Control characters, quotes and the characters a header or a path would read.
+    const base = Array.from(last).filter((character)=>{
+        const code = character.charCodeAt(0);
+        return code >= 32 && code !== 127 && !'"<>|:*?%;'.includes(character);
+    }).join('').replace(/\s+/g, ' ').trim();
+    const extension = extensionOf(base);
+    const stem = (type.extensions.includes(extension) ? base.slice(0, -extension.length) : base).trim();
+    const kept = (stem || 'file').slice(0, 120 - 6).trim() || 'file';
+    return `${kept}${type.extensions.includes(extension) ? extension : type.extensions[0]}`;
+}
+/**
+ * Checks what the browser asks to send, before anything is signed: one of
+ * the types taken, not empty, not over the size. The answer's `error` names
+ * the file and what to do.
+ */ export function checkVisitorUploadRequest(raw, options = {}) {
+    var _options_maxBytes;
+    var _name_split_pop;
+    const source = raw && typeof raw === 'object' ? raw : {};
+    const name = typeof source['name'] === 'string' ? source['name'].slice(0, 400) : '';
+    const size = Number(source['size']);
+    const shown = ((_name_split_pop = name.split(/[\\/]/).pop()) == null ? void 0 : _name_split_pop.trim()) || 'This file';
+    const type = resolveVisitorUploadType(name, typeof source['contentType'] === 'string' ? source['contentType'] : '');
+    if (!type) {
+        return {
+            ok: false,
+            code: 'type',
+            error: `${shown} can't be sent. Send a ${describeVisitorUploadTypes()} file.`
+        };
+    }
+    if (!Number.isSafeInteger(size) || size <= 0) {
+        return {
+            ok: false,
+            code: 'empty',
+            error: `${shown} is empty.`
+        };
+    }
+    const maxBytes = Math.min((_options_maxBytes = options.maxBytes) != null ? _options_maxBytes : VISITOR_UPLOAD_MAX_BYTES, VISITOR_UPLOAD_MAX_BYTES);
+    if (size > maxBytes) {
+        return {
+            ok: false,
+            code: 'size',
+            error: `${shown} is ${formatVisitorUploadBytes(size)}. Files can be up to ${formatVisitorUploadBytes(maxBytes)}.`
+        };
+    }
+    return {
+        ok: true,
+        upload: {
+            name: safeVisitorUploadName(name, type),
+            type,
+            size
+        }
+    };
+}
+/** The record without its storage path. */ export function visitorUploadFileView(file) {
+    return {
+        id: file.id,
+        name: file.name,
+        contentType: file.contentType,
+        size: file.size,
+        uploadedAtMs: file.uploadedAtMs
+    };
+}
+/** A purpose or a record id as a path segment: letters, digits, `-` and `_`, and not too long. */ const SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+export function isVisitorUploadSegment(value) {
+    return typeof value === 'string' && SEGMENT.test(value);
+}
+/** Whether every part of a scope can be a path segment. */ export function isVisitorUploadScope(scope) {
+    return isVisitorUploadSegment(scope.hostId) && isVisitorUploadSegment(scope.purpose) && isVisitorUploadSegment(scope.purposeId);
+}
+/** Where a file waits between the browser's upload and its check. */ export function visitorUploadPendingPath(scope, uploadId) {
+    return `${VISITOR_UPLOAD_PENDING_PREFIX}${scope.hostId}/${scope.purpose}/${scope.purposeId}/${uploadId}`;
+}
+/** The folder every kept file of one purpose and record is in. */ export function visitorUploadFolder(scope) {
+    return `hosts/${scope.hostId}/private/uploads/${scope.purpose}/${scope.purposeId}/`;
+}
+/** Where a checked file is kept: private to the site, with no download token. */ export function visitorUploadFinalPath(scope, uploadId) {
+    return `${visitorUploadFolder(scope)}${uploadId}`;
+}
+/**
+ * The files a browser picked, checked before any is sent: how many, and each
+ * one's type and size. `already` is how many the submission holds.
+ */ export function checkVisitorUploadSelection(files, already = 0, maxFiles = VISITOR_UPLOAD_MAX_FILES) {
+    if (already + files.length > maxFiles) {
+        return `Send up to ${maxFiles} files at a time.`;
+    }
+    for (const file of files){
+        const checked = checkVisitorUploadRequest({
+            name: file.name,
+            contentType: file.type,
+            size: file.size
+        });
+        if ('error' in checked) return checked.error;
+    }
+    return null;
+}
+
+//# sourceMappingURL=visitor-upload.js.map

package/src/lib/app-utils/visitor-upload.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/visitor-upload.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * FILES A VISITOR SENDS A BUSINESS (AGL-4096).\n *\n * Artwork for a quote, a logo with a request form: files someone without an\n * account hands a business through its site. This module is the policy, pure\n * and shared by the browser and the server:\n *\n * - which files are taken ({@link VISITOR_UPLOAD_TYPES}: PNG, JPEG, WebP,\n *   GIF, PDF, SVG, AI, EPS, PSD, TIFF), how big ({@link VISITOR_UPLOAD_MAX_BYTES})\n *   and how many at once ({@link VISITOR_UPLOAD_MAX_FILES});\n * - what a file's type IS ({@link resolveVisitorUploadType}): read from its\n *   name and checked against what the browser said, so a `.psd` a browser\n *   labels `application/octet-stream` is still a Photoshop file and a `.png`\n *   labelled `text/html` is nothing;\n * - where its bytes live ({@link visitorUploadPendingPath} while it is on its\n *   way, {@link visitorUploadFinalPath} once it is checked);\n * - the record a finished upload is ({@link VisitorUploadFile}).\n *\n * The server half (`@aglyn/tenant-data-admin/server/visitor-upload`) signs the\n * upload, inspects the bytes and moves them; the browser half\n * (`visitor-upload-client.ts`) sends them. A plugin that takes files (commerce\n * for a quote's artwork, forms for a request) names its own `purpose` and the\n * record it is for, and decides for itself who may upload for it.\n *=========================================*/\n\n/** The most one file may weigh. */\nexport const VISITOR_UPLOAD_MAX_BYTES = 25 * 1024 * 1024\n\n/** The most files one submission carries. */\nexport const VISITOR_UPLOAD_MAX_FILES = 10\n\n/** How long the signed upload a ticket carries can be used, from its minting. */\nexport const VISITOR_UPLOAD_TICKET_TTL_MS = 15 * 60 * 1000\n\n/**\n * Where uploads wait until they are checked. Top-level, never under `hosts/`:\n * the bucket's lifecycle deletes whatever is still here a day after it\n * arrived (`cloud/media-bucket-lifecycle.json`), which no rule may do under a\n * prefix that holds live customer files.\n */\nexport const VISITOR_UPLOAD_PENDING_PREFIX = 'visitor-uploads-pending/'\n\n/** The honeypot field a form posts beside its files, as the forms plugin names it. */\nexport const VISITOR_UPLOAD_HONEYPOT_FIELD = 'website'\n\n/** One kind of file a visitor may send. */\nexport interface VisitorUploadType {\n  /** The type the file is stored and served as. */\n  contentType: string\n  /** Lower-case, with the dot. The first is the one a file is renamed to when it has none. */\n  extensions: readonly string[]\n  /** What a person calls it. */\n  label: string\n  /**\n   * Shown in the page as a picture. Only raster formats a browser draws and\n   * that cannot carry script; everything else downloads.\n   */\n  inline: boolean\n  /** Other types a browser reports for this kind of file. */\n  aliases?: readonly string[]\n}\n\nexport const VISITOR_UPLOAD_TYPES: readonly VisitorUploadType[] = [\n  { contentType: 'image/png', extensions: ['.png'], label: 'PNG', inline: true },\n  { contentType: 'image/jpeg', extensions: ['.jpg', '.jpeg'], label: 'JPEG', inline: true, aliases: ['image/jpg', 'image/pjpeg'] },\n  { contentType: 'image/webp', extensions: ['.webp'], label: 'WebP', inline: true },\n  { contentType: 'image/gif', extensions: ['.gif'], label: 'GIF', inline: true },\n  { contentType: 'application/pdf', extensions: ['.pdf'], label: 'PDF', inline: false, aliases: ['application/x-pdf'] },\n  // Stripped of script on the way in, and still downloaded rather than drawn.\n  { contentType: 'image/svg+xml', extensions: ['.svg'], label: 'SVG', inline: false },\n  {\n    contentType: 'application/illustrator',\n    extensions: ['.ai'],\n    label: 'AI',\n    inline: false,\n    aliases: ['application/postscript', 'application/pdf', 'application/vnd.adobe.illustrator'],\n  },\n  { contentType: 'application/postscript', extensions: ['.eps'], label: 'EPS', inline: false, aliases: ['application/eps', 'image/eps', 'image/x-eps', 'application/x-eps'] },\n  {\n    contentType: 'image/vnd.adobe.photoshop',\n    extensions: ['.psd'],\n    label: 'PSD',\n    inline: false,\n    aliases: ['application/x-photoshop', 'application/photoshop', 'application/psd', 'image/psd', 'image/x-photoshop'],\n  },\n  { contentType: 'image/tiff', extensions: ['.tif', '.tiff'], label: 'TIFF', inline: false, aliases: ['image/x-tiff'] },\n]\n\n/** Types a browser sends when it does not know; the name decides then. */\nconst UNKNOWN_TYPES = new Set(['', 'application/octet-stream', 'binary/octet-stream', 'application/unknown'])\n\n/** `PNG, JPEG, WebP, GIF, PDF, SVG, AI, EPS, PSD or TIFF`. */\nexport function describeVisitorUploadTypes(): string {\n  const labels = VISITOR_UPLOAD_TYPES.map((type) => type.label)\n  return `${labels.slice(0, -1).join(', ')} or ${labels[labels.length - 1]}`\n}\n\n/** The file picker's `accept`: every extension and type taken. */\nexport const VISITOR_UPLOAD_ACCEPT = VISITOR_UPLOAD_TYPES.flatMap((type) => [\n  ...type.extensions,\n  type.contentType,\n]).join(',')\n\n/** `25 MB`. */\nexport function formatVisitorUploadBytes(bytes: number): string {\n  if (!(bytes > 0)) return '0 KB'\n  if (bytes < 1024 * 1024) return `${Math.max(1, Math.round(bytes / 1024))} KB`\n  const mb = bytes / (1024 * 1024)\n  return `${mb >= 10 ? Math.round(mb) : Math.round(mb * 10) / 10} MB`\n}\n\n/** The extension of a file name, lower-case with its dot, or ''. */\nfunction extensionOf(name: string): string {\n  const dot = name.lastIndexOf('.')\n  return dot > 0 ? name.slice(dot).toLowerCase() : ''\n}\n\n/**\n * The type a file is taken as, or null when it is not one this takes. The\n * NAME decides, because a browser reports most design files as nothing or as\n * something generic; the reported type only has to agree with it (be this\n * type, one it is known by, or unknown). The bytes are checked against the\n * answer after they arrive.\n */\nexport function resolveVisitorUploadType(name: string, reportedType: string): VisitorUploadType | null {\n  const extension = extensionOf(String(name ?? ''))\n  const reported = String(reportedType ?? '').split(';')[0].trim().toLowerCase()\n  const byName = VISITOR_UPLOAD_TYPES.find((type) => type.extensions.includes(extension))\n  if (!byName) return null\n  if (UNKNOWN_TYPES.has(reported) || reported === byName.contentType) return byName\n  return byName.aliases?.includes(reported) ? byName : null\n}\n\n/** A stored type, as the list of types knows it; null for anything else. */\nexport function visitorUploadTypeOf(contentType: string): VisitorUploadType | null {\n  return VISITOR_UPLOAD_TYPES.find((type) => type.contentType === contentType) ?? null\n}\n\n/** Whether a stored file may be shown as a picture rather than downloaded. */\nexport function visitorUploadIsInline(contentType: string): boolean {\n  return visitorUploadTypeOf(contentType)?.inline === true\n}\n\n/**\n * A file name safe to keep and to put in a download's header: no folders, no\n * control or quoting characters, at most 120 characters, and ending in the\n * extension of the type it was taken as.\n */\nexport function safeVisitorUploadName(name: string, type: VisitorUploadType): string {\n  const last = String(name ?? '').split(/[\\\\/]/).pop() ?? ''\n  // Control characters, quotes and the characters a header or a path would read.\n  const base = Array.from(last)\n    .filter((character) => {\n      const code = character.charCodeAt(0)\n      return code >= 32 && code !== 127 && !'\"<>|:*?%;'.includes(character)\n    })\n    .join('')\n    .replace(/\\s+/g, ' ')\n    .trim()\n  const extension = extensionOf(base)\n  const stem = (type.extensions.includes(extension) ? base.slice(0, -extension.length) : base).trim()\n  const kept = (stem || 'file').slice(0, 120 - 6).trim() || 'file'\n  return `${kept}${type.extensions.includes(extension) ? extension : type.extensions[0]}`\n}\n\n/** What the browser asks to upload: a file's name, its reported type and its size. */\nexport interface VisitorUploadRequest {\n  name: string\n  contentType: string\n  size: number\n}\n\n/** A request, checked: the type it is taken as and a safe name. */\nexport interface CheckedVisitorUpload {\n  name: string\n  type: VisitorUploadType\n  size: number\n}\n\n/**\n * Checks what the browser asks to send, before anything is signed: one of\n * the types taken, not empty, not over the size. The answer's `error` names\n * the file and what to do.\n */\nexport function checkVisitorUploadRequest(\n  raw: unknown,\n  options: { maxBytes?: number } = {},\n): { ok: true; upload: CheckedVisitorUpload } | { ok: false; error: string; code: 'type' | 'size' | 'empty' } {\n  const source = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>\n  const name = typeof source['name'] === 'string' ? source['name'].slice(0, 400) : ''\n  const size = Number(source['size'])\n  const shown = name.split(/[\\\\/]/).pop()?.trim() || 'This file'\n  const type = resolveVisitorUploadType(name, typeof source['contentType'] === 'string' ? source['contentType'] : '')\n  if (!type) {\n    return {\n      ok: false,\n      code: 'type',\n      error: `${shown} can't be sent. Send a ${describeVisitorUploadTypes()} file.`,\n    }\n  }\n  if (!Number.isSafeInteger(size) || size <= 0) {\n    return { ok: false, code: 'empty', error: `${shown} is empty.` }\n  }\n  const maxBytes = Math.min(options.maxBytes ?? VISITOR_UPLOAD_MAX_BYTES, VISITOR_UPLOAD_MAX_BYTES)\n  if (size > maxBytes) {\n    return {\n      ok: false,\n      code: 'size',\n      error: `${shown} is ${formatVisitorUploadBytes(size)}. Files can be up to ${formatVisitorUploadBytes(maxBytes)}.`,\n    }\n  }\n  return { ok: true, upload: { name: safeVisitorUploadName(name, type), type, size } }\n}\n\n/** A file a visitor or a member sent, once it is checked and kept. */\nexport interface VisitorUploadFile {\n  /** Unique within its purpose and record. */\n  id: string\n  /** The name it was sent with, made safe. */\n  name: string\n  contentType: string\n  /** Bytes, as stored (an SVG may shrink when its script is stripped). */\n  size: number\n  /** The private Storage object. Never sent to a visitor. */\n  path: string\n  uploadedAtMs: number\n}\n\n/** A file as a visitor's page may see it: no storage path. */\nexport type VisitorUploadFileView = Omit<VisitorUploadFile, 'path'>\n\n/** The record without its storage path. */\nexport function visitorUploadFileView(file: VisitorUploadFile): VisitorUploadFileView {\n  return { id: file.id, name: file.name, contentType: file.contentType, size: file.size, uploadedAtMs: file.uploadedAtMs }\n}\n\n/** A purpose or a record id as a path segment: letters, digits, `-` and `_`, and not too long. */\nconst SEGMENT = /^[A-Za-z0-9_-]{1,128}$/\n\nexport function isVisitorUploadSegment(value: unknown): value is string {\n  return typeof value === 'string' && SEGMENT.test(value)\n}\n\n/** What an upload is for: the site, what kind of thing (`quote-artwork`), and which one. */\nexport interface VisitorUploadScope {\n  hostId: string\n  purpose: string\n  purposeId: string\n}\n\n/** Whether every part of a scope can be a path segment. */\nexport function isVisitorUploadScope(scope: Partial<VisitorUploadScope>): scope is VisitorUploadScope {\n  return isVisitorUploadSegment(scope.hostId) && isVisitorUploadSegment(scope.purpose) && isVisitorUploadSegment(scope.purposeId)\n}\n\n/** Where a file waits between the browser's upload and its check. */\nexport function visitorUploadPendingPath(scope: VisitorUploadScope, uploadId: string): string {\n  return `${VISITOR_UPLOAD_PENDING_PREFIX}${scope.hostId}/${scope.purpose}/${scope.purposeId}/${uploadId}`\n}\n\n/** The folder every kept file of one purpose and record is in. */\nexport function visitorUploadFolder(scope: VisitorUploadScope): string {\n  return `hosts/${scope.hostId}/private/uploads/${scope.purpose}/${scope.purposeId}/`\n}\n\n/** Where a checked file is kept: private to the site, with no download token. */\nexport function visitorUploadFinalPath(scope: VisitorUploadScope, uploadId: string): string {\n  return `${visitorUploadFolder(scope)}${uploadId}`\n}\n\n/**\n * The files a browser picked, checked before any is sent: how many, and each\n * one's type and size. `already` is how many the submission holds.\n */\nexport function checkVisitorUploadSelection(\n  files: ReadonlyArray<{ name: string; type: string; size: number }>,\n  already = 0,\n  maxFiles = VISITOR_UPLOAD_MAX_FILES,\n): string | null {\n  if (already + files.length > maxFiles) {\n    return `Send up to ${maxFiles} files at a time.`\n  }\n  for (const file of files) {\n    const checked = checkVisitorUploadRequest({ name: file.name, contentType: file.type, size: file.size })\n    if ('error' in checked) return checked.error\n  }\n  return null\n}\n"],"names":["VISITOR_UPLOAD_MAX_BYTES","VISITOR_UPLOAD_MAX_FILES","VISITOR_UPLOAD_TICKET_TTL_MS","VISITOR_UPLOAD_PENDING_PREFIX","VISITOR_UPLOAD_HONEYPOT_FIELD","VISITOR_UPLOAD_TYPES","contentType","extensions","label","inline","aliases","UNKNOWN_TYPES","Set","describeVisitorUploadTypes","labels","map","type","slice","join","length","VISITOR_UPLOAD_ACCEPT","flatMap","formatVisitorUploadBytes","bytes","Math","max","round","mb","extensionOf","name","dot","lastIndexOf","toLowerCase","resolveVisitorUploadType","reportedType","byName","extension","String","reported","split","trim","find","includes","has","visitorUploadTypeOf","visitorUploadIsInline","safeVisitorUploadName","last","pop","base","Array","from","filter","character","code","charCodeAt","replace","stem","kept","checkVisitorUploadRequest","raw","options","source","size","Number","shown","ok","error","isSafeInteger","maxBytes","min","upload","visitorUploadFileView","file","id","uploadedAtMs","SEGMENT","isVisitorUploadSegment","value","test","isVisitorUploadScope","scope","hostId","purpose","purposeId","visitorUploadPendingPath","uploadId","visitorUploadFolder","visitorUploadFinalPath","checkVisitorUploadSelection","files","already","maxFiles","checked"],"mappings":"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"}

package/src/lib/foundation/definitions/platform.types.d.ts

@@ -507,6 +507,33 @@ export interface AglynHost extends AglynDocument {
     authScreens?: HostAuthScreens;
     /** Maintenance mode (AGL-131): every path renders the 503 screen. */
     maintenance?: boolean;
+    /**
+     * Preview (AGL-4086): only the site's team, and Aglyn staff, see the site;
+     * the public gets the 503 page or a "Coming soon" notice at every address.
+     * Unlike `maintenance`, which replaces the site for EVERYONE, this keeps the
+     * whole site working for the people building it.
+     *
+     * ADMIN-SDK ONLY: written by `/api/hosts/preview` (a site admin) and by
+     * `/api/hosts/create` (the create flow's Start in preview choice). The
+     * console never writes it from the client, because flipping it public is a
+     * launch: it reports `site_published` once and drops every cached page.
+     */
+    preview?: boolean;
+    /**
+     * The pages in preview on a site that is otherwise public (AGL-4086):
+     * screen id → `true`. A page in preview answers the public with the site's
+     * 404 and its team with the page. Kept on the host rather than the screen
+     * so the middleware's verdict, which holds only the host document, can
+     * route the team around the cache at exactly those addresses.
+     */
+    previewScreens?: Record<ScreenUid, boolean>;
+    /**
+     * When the site was first public after a stretch in preview, or when it
+     * was put into preview while public (AGL-4086). Its presence is what tells
+     * the switch the site has been public before, so `site_published` is
+     * reported once and never again. Epoch ms. Admin-SDK only, with `preview`.
+     */
+    publicSinceMs?: number;
     /**
      * STAFF host takedown (AGL-1501) — the host scope of the panic button,
      * for an infected or abusive site. The same field family as the org's