@fullgrainsoftware/portal 0.11.0 → 0.12.1

package/README.md

@@ -159,6 +159,99 @@ bad key, or any other unexpected response — already logged via
 `console.error`), fall back to a mailto/phone link rather than a dead form.
 Ask your Fullgrain Software contact for the `INQUIRY_API_KEY` (`abik_…`).
 
+### Attachments (photos)
+
+A contact form can carry up to five photos. The panel admin turns **Accept
+photos** on for the site first (the site's Inbox tab); until then every
+upload answers `disabled`. Photos go browser → the site's own route →
+`uploadPhoto`, one photo per request, and the message then names them by id.
+
+In the browser, prepare each picked file before it leaves the device:
+
+```ts
+import { PHOTO_LIMITS, PhotoError, isPhotoCandidate, preparePhoto } from "@fullgrainsoftware/portal";
+
+// <input type="file" accept={PHOTO_LIMITS.accept} multiple>  — at most PHOTO_LIMITS.perInquiry (5) photos
+if (!isPhotoCandidate(file)) { /* not a photo — tell the visitor, skip it */ }
+try {
+  const jpeg = await preparePhoto(file);   // a JPEG File, ≤ 1568 px on the long side, EXIF (GPS included) dropped
+  const body = new FormData();
+  body.append("file", jpeg);
+  const res = await fetch("/api/contact/photo", { method: "POST", body });   // the site's route, one photo per request → { id } or an error word
+} catch (err) {
+  if (err instanceof PhotoError) showOnTile(err.message);   // err.code: "unsupported" | "unreadable" | "too_large"
+}
+```
+
+`preparePhoto(file, { maxEdge?, quality? })` decodes with the browser's own
+decoder (keeping the photo's orientation), scales to fit `PHOTO_LIMITS.maxEdge`
+(1568) without enlarging, and re-encodes as `<name>.jpg` at quality 0.85.
+It is browser-only: on the server it rejects with `unsupported`. Every failure
+is a `PhotoError` whose `message` is written for the visitor and safe to show
+as is: `unsupported` (not a type it takes), `unreadable` (the browser couldn't
+decode it, or the file is corrupt), `too_large` (still over
+`PHOTO_LIMITS.maxUploadBytes`, 4 MiB, after the resize). `isPhotoCandidate` is
+the same type check, for the picker's own validation: the
+`PHOTO_LIMITS.accept` types (JPEG, PNG, WebP, GIF), the HEIC family, and a
+file with no type (or `application/octet-stream`) whose name ends in one of
+those extensions. A HEIC reaches the decoder: Safari and iOS decode it, other
+browsers reject it as `unreadable`. `PHOTO_LIMITS.accept` leaves HEIC out on
+purpose, so iOS converts to JPEG in the picker; the SDK ships no HEIC decoder.
+
+On the server, the site's route forwards the file and the submit names the ids:
+
+```ts
+// app/api/contact/photo/route.ts
+import { PHOTO_LIMITS, createInquiries } from "@fullgrainsoftware/portal";
+
+const form = await req.formData();
+const file = form.get("file");
+if (!(file instanceof Blob)) return badRequest();
+if (file.size > PHOTO_LIMITS.maxUploadBytes) return tooLarge();
+const apiKey = process.env.INQUIRY_API_KEY;
+if (!apiKey?.startsWith("abik_")) return unavailable();   // 503 — "photos can't be added right now"
+const inquiries = createInquiries({ apiKey });             // inside the handler, as for submit
+const result = await inquiries.uploadPhoto({ file, meta: { ip, userAgent } });   // a File's own name is sent as `name`
+// { ok: true, id, width, height, bytes }
+// { ok: false, error: "invalid", issues: Record<string, string> }   e.g. issues.file: "That photo couldn't be read."
+// { ok: false, error: "too_large" | "unsupported_type" | "rate_limited" | "disabled" | "unavailable" }
+
+// app/api/contact/route.ts — later, with the ids the browser kept, in display order
+await inquiries.submit({ name, email, message, attachments: ids /* ≤ 5 */ });
+```
+
+The panel re-checks every photo (by its own bytes, never the type the browser
+claims), re-encodes it, stores it privately, and keeps an unattached upload for 24
+hours: `submit` must name it within that window, or it answers `invalid` with
+`issues.attachments` ("One of the photos expired. Add it again."; with
+**Accept photos** off, "This site doesn't accept photos."); show that issue on
+the photo strip. Removing a photo before sending just drops its id. Turn the
+upload result into copy: `invalid` → the first text in `issues` (usually
+`issues.file`; an over-long name is `issues.name`),
+`too_large` → "That photo is too big", `unsupported_type` → "Use a JPEG or
+PNG", `rate_limited` → "Try again in a few minutes" (20 uploads per visitor
+per 10 minutes, 300 per site per hour), and `disabled`, `unavailable` or a
+missing key → "Photos can't be added right now — send the message and email
+them to us." **A photo failure never disables sending the message**: the form
+submits with whichever photos succeeded. A `rate_limited` submit leaves the
+photos attachable, so keep the ids and send them again on the retry.
+
+Keep each request to one photo. The panel takes at most 4 MiB per file
+(`uploadPhoto` sends whatever it is given; check the size in your route), and
+Vercel refuses a function body over 4.5 MB with its own 413 before the code
+runs, on your route as on the panel's (`uploadPhoto` maps any 413, JSON or
+not, to `too_large`), so several photos in one request fail where one would
+not.
+
+Two rules every site keeps:
+
+- **Never show a visitor's photo on the public site.** Photos are for the
+  business's inbox only; the panel serves them to signed-in users and nowhere
+  else.
+- **Reviews refuse attachments.** A `form: "review"` submit with
+  `attachments` is `invalid` ("Photos can't be attached to a review."), so
+  leave the picker off review forms.
+
 ## Bookings (appointments)
 
 For sites whose business takes appointments. **Server-only** — the API key

package/dist/index.d.ts

@@ -8,8 +8,10 @@ export type { CMSComponent, CMSPage, CMSReview, CMSSection, CMSSectionGroup, CMS
 export { createCommerce } from "./commerce.js";
 export type { CartPreview, CheckoutInput, CheckoutResult, Commerce, LineIssue, OrderStatus, ProductDetail, ProductSummary, StoreStatus, VariantView, } from "./commerce.js";
 export { createInquiries } from "./inquiries.js";
-export type { Inquiries, InquiryInput, InquirySubmitResult } from "./inquiries.js";
+export type { Inquiries, InquiryInput, InquirySubmitResult, InquiryUploadInput, InquiryUploadResult, } from "./inquiries.js";
 export { initCmsPreview, normalizeSectionTitle, parseInbound, readyMessage, sectionClickedMessage, editItemMessage, PREVIEW_PROTOCOL_VERSION, PREVIEW_QUERY_FLAG, } from "./preview.js";
 export type { CmsPreviewOptions, PreviewInbound, PreviewOutbound } from "./preview.js";
+export { PHOTO_LIMITS, PhotoError, isPhotoCandidate, preparePhoto } from "./photos.js";
+export type { PhotoErrorCode, PreparePhotoOptions } from "./photos.js";
 export { createBookings } from "./bookings.js";
 export type { AvailabilityDay, AvailabilityResult, BookInput, BookResult, BookingCustomer, BookingService, BookingStatus, BookingView, Bookings, GetBookingResult, ManageResult, RequestTimeInput, RequestTimeResult, ServicesResult, } from "./bookings.js";

package/dist/index.js

@@ -5,4 +5,5 @@ export { readReviews } from "./reviews.js";
 export { createCommerce } from "./commerce.js";
 export { createInquiries } from "./inquiries.js";
 export { initCmsPreview, normalizeSectionTitle, parseInbound, readyMessage, sectionClickedMessage, editItemMessage, PREVIEW_PROTOCOL_VERSION, PREVIEW_QUERY_FLAG, } from "./preview.js";
+export { PHOTO_LIMITS, PhotoError, isPhotoCandidate, preparePhoto } from "./photos.js";
 export { createBookings } from "./bookings.js";

package/dist/inquiries.d.ts

@@ -13,11 +13,37 @@ export interface InquiryInput {
     page?: string | null;
     /** A hidden field a human never fills; non-empty means a bot. */
     honeypot?: string | null;
+    /** Ids from `uploadPhoto`, in display order, at most 5. */
+    attachments?: string[];
     meta?: {
         ip?: string | null;
         userAgent?: string | null;
     };
 }
+export interface InquiryUploadInput {
+    /** The photo: a browser `File` passed through, or any `Blob`. */
+    file: Blob;
+    /** The visitor's filename, shown in the inbox. Defaults to the `File`'s own name. */
+    name?: string;
+    meta?: {
+        ip?: string | null;
+        userAgent?: string | null;
+    };
+}
+export type InquiryUploadResult = {
+    ok: true;
+    id: string;
+    width: number;
+    height: number;
+    bytes: number;
+} | {
+    ok: false;
+    error: "invalid";
+    issues: Record<string, string>;
+} | {
+    ok: false;
+    error: "too_large" | "unsupported_type" | "rate_limited" | "disabled" | "unavailable";
+};
 export type InquirySubmitResult = {
     ok: true;
     id: string;
@@ -31,6 +57,8 @@ export type InquirySubmitResult = {
 };
 export interface Inquiries {
     submit(input: InquiryInput): Promise<InquirySubmitResult>;
+    /** Stores one photo ahead of the submit; pass the returned id in `attachments`. */
+    uploadPhoto(input: InquiryUploadInput): Promise<InquiryUploadResult>;
 }
 export declare function createInquiries(opts: {
     apiKey: string;

package/dist/inquiries.js

@@ -5,6 +5,8 @@
    into its own success, "try again in a few minutes", or fallback state. */
 const DEFAULT_BASE_URL = "https://app.fullgrainsoftware.com";
 const TIMEOUT_MS = 10_000;
+/** An upload carries up to 4 MiB over the hop, so it gets longer than a submit. */
+const UPLOAD_TIMEOUT_MS = 20_000;
 export function createInquiries(opts) {
     if (typeof window !== "undefined") {
         throw new Error("createInquiries is server-only — never expose INQUIRY_API_KEY to the browser");
@@ -14,6 +16,7 @@ export function createInquiries(opts) {
     }
     const base = (opts.baseUrl ?? process.env.AB_CMS_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     const path = "/api/inquiries/submit";
+    const uploadPath = "/api/inquiries/uploads";
     const unavailable = (why) => {
         console.error(`[fullgrain inquiries] ${why}`);
         return { ok: false, error: "unavailable" };
@@ -48,5 +51,60 @@ export function createInquiries(opts) {
                 return { ok: false, error: "rate_limited" };
             return unavailable(`unexpected response ${res.status}${body?.error ? ` (${body.error})` : ""} from ${base}${path}`);
         },
+        async uploadPhoto(input) {
+            const form = new FormData();
+            // A File carries its own name; an explicit `name` wins over it.
+            const name = input.name ?? (typeof input.file.name === "string" ? input.file.name : undefined);
+            if (name)
+                form.append("file", input.file, name);
+            else
+                form.append("file", input.file);
+            if (name)
+                form.append("name", name);
+            if (input.meta?.ip != null)
+                form.append("ip", input.meta.ip);
+            if (input.meta?.userAgent != null)
+                form.append("user_agent", input.meta.userAgent);
+            let res;
+            try {
+                // No Content-Type by hand: the runtime writes the multipart boundary.
+                res = await fetch(`${base}${uploadPath}`, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${opts.apiKey}` },
+                    body: form,
+                    cache: "no-store",
+                    signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+                });
+            }
+            catch (err) {
+                return unavailable(`request failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // Before the content-type check: above 4.5 MB Vercel answers its own HTML 413.
+            if (res.status === 413)
+                return { ok: false, error: "too_large" };
+            const contentType = res.headers.get("content-type") ?? "";
+            if (!contentType.includes("application/json")) {
+                return unavailable(`non-JSON response ${res.status} from ${base}${uploadPath}`);
+            }
+            const body = (await res.json().catch(() => null));
+            if (res.status === 200 && body?.ok && typeof body.id === "string") {
+                return {
+                    ok: true,
+                    id: body.id,
+                    width: Number(body.width ?? 0),
+                    height: Number(body.height ?? 0),
+                    bytes: Number(body.bytes ?? 0),
+                };
+            }
+            if (res.status === 400 && body?.error === "invalid")
+                return { ok: false, error: "invalid", issues: body.issues ?? {} };
+            if (res.status === 403)
+                return { ok: false, error: "disabled" };
+            if (res.status === 415)
+                return { ok: false, error: "unsupported_type" };
+            if (res.status === 429)
+                return { ok: false, error: "rate_limited" };
+            return unavailable(`unexpected response ${res.status} from ${base}${uploadPath}`);
+        },
     };
 }

package/dist/photos.d.ts

@@ -0,0 +1,37 @@
+export declare const PHOTO_LIMITS: {
+    readonly perInquiry: 5;
+    readonly maxEdge: 1568;
+    readonly maxUploadBytes: number;
+    readonly accept: "image/jpeg,image/png,image/webp,image/gif";
+};
+export type PhotoErrorCode = "unsupported" | "unreadable" | "too_large";
+export declare class PhotoError extends Error {
+    readonly code: PhotoErrorCode;
+    constructor(code: PhotoErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+export interface PreparePhotoOptions {
+    /** Longest side of the result in pixels. Default PHOTO_LIMITS.maxEdge (1568); anything not a finite number ≥ 1 uses it. */
+    maxEdge?: number;
+    /** JPEG quality in (0, 1]. Default 0.85; anything outside that range uses it. */
+    quality?: number;
+}
+/**
+ * Whether a picked file is worth handing to the browser's decoder: one of
+ * PHOTO_LIMITS.accept's types, or the HEIC family — by type, or by name when
+ * the browser reports no type (an empty type or application/octet-stream):
+ * a .jpg/.jpeg/.png/.webp/.gif name (some Android cloud and document pickers
+ * report no type) or a .heic/.heif/.hif name (Windows Chrome gives a .heic an
+ * empty type). A stated non-image type wins over the name. Safari and iOS
+ * decode HEIC natively; elsewhere preparePhoto then rejects it as
+ * "unreadable". PHOTO_LIMITS.accept itself leaves HEIC out on purpose, so iOS
+ * keeps converting to JPEG in the picker.
+ * Sites can reuse this for their own picker validation.
+ */
+export declare function isPhotoCandidate(file: Pick<File, "name" | "type">): boolean;
+/**
+ * Resize a picked image to a JPEG of at most `maxEdge` px on its long side,
+ * without EXIF. Browser-only: on the server it rejects with "unsupported".
+ */
+export declare function preparePhoto(file: File, options?: PreparePhotoOptions): Promise<File>;

package/dist/photos.js

@@ -0,0 +1,121 @@
+// Browser helper for inquiry photos. A site calls preparePhoto in the
+// visitor's browser before posting the picked file to its own route (which
+// forwards it with inquiries.uploadPhoto). It decodes the image with the
+// browser's own decoder, keeps the photo's orientation, scales it to at most
+// PHOTO_LIMITS.maxEdge on the long side (never enlarging) and re-encodes it
+// as a JPEG on a canvas filled white first, so transparency flattens onto
+// white. Orientation is applied by the decoder: createImageBitmap's default
+// is the photo's EXIF orientation. No imageOrientation option is passed, for
+// browser compatibility: the "from-image" value exists only from Chrome 112,
+// Firefox 111 and Safari 16, and an unknown enum value rejects the call. A
+// HEIC is handed to the decoder too (see isPhotoCandidate): Safari and iOS
+// decode it, other browsers reject it as "unreadable".
+//
+// The canvas re-encode carries no EXIF at all, so camera metadata — GPS
+// coordinates included — never leaves the visitor's device.
+//
+// Failures reject with a PhotoError: a stable `code` for the site's logic and
+// a `message` written for the visitor, safe to show as is (it never echoes
+// the file's name or contents).
+export const PHOTO_LIMITS = {
+    perInquiry: 5,
+    maxEdge: 1568,
+    maxUploadBytes: 4 * 1024 * 1024,
+    accept: "image/jpeg,image/png,image/webp,image/gif",
+};
+const MESSAGES = {
+    unsupported: "That file isn't a photo we can take. Use a JPEG or PNG.",
+    unreadable: "That photo couldn't be read. Try a JPEG or PNG.",
+    too_large: "That photo is too large.",
+};
+export class PhotoError extends Error {
+    code;
+    constructor(code, options) {
+        super(MESSAGES[code], options);
+        this.name = "PhotoError";
+        this.code = code;
+    }
+}
+const DEFAULT_QUALITY = 0.85;
+const ACCEPTED_TYPES = PHOTO_LIMITS.accept.split(",");
+const HEIC_TYPES = ["image/heic", "image/heif", "image/heic-sequence", "image/heif-sequence"];
+const HEIC_NAME = /\.(heic|heif|hif)$/i;
+const PHOTO_NAME = /\.(jpe?g|png|webp|gif)$/i;
+/**
+ * Whether a picked file is worth handing to the browser's decoder: one of
+ * PHOTO_LIMITS.accept's types, or the HEIC family — by type, or by name when
+ * the browser reports no type (an empty type or application/octet-stream):
+ * a .jpg/.jpeg/.png/.webp/.gif name (some Android cloud and document pickers
+ * report no type) or a .heic/.heif/.hif name (Windows Chrome gives a .heic an
+ * empty type). A stated non-image type wins over the name. Safari and iOS
+ * decode HEIC natively; elsewhere preparePhoto then rejects it as
+ * "unreadable". PHOTO_LIMITS.accept itself leaves HEIC out on purpose, so iOS
+ * keeps converting to JPEG in the picker.
+ * Sites can reuse this for their own picker validation.
+ */
+export function isPhotoCandidate(file) {
+    const type = file.type.toLowerCase();
+    if (ACCEPTED_TYPES.includes(type) || HEIC_TYPES.includes(type))
+        return true;
+    if (type === "" || type === "application/octet-stream")
+        return PHOTO_NAME.test(file.name) || HEIC_NAME.test(file.name);
+    return false;
+}
+/**
+ * Resize a picked image to a JPEG of at most `maxEdge` px on its long side,
+ * without EXIF. Browser-only: on the server it rejects with "unsupported".
+ */
+export async function preparePhoto(file, options = {}) {
+    if (typeof document === "undefined")
+        throw new PhotoError("unsupported");
+    if (!isPhotoCandidate(file))
+        throw new PhotoError("unsupported");
+    let bitmap;
+    try {
+        bitmap = await createImageBitmap(file);
+    }
+    catch (cause) {
+        throw new PhotoError("unreadable", { cause });
+    }
+    let blob;
+    try {
+        const maxEdge = typeof options.maxEdge === "number" && Number.isFinite(options.maxEdge) && options.maxEdge >= 1
+            ? options.maxEdge
+            : PHOTO_LIMITS.maxEdge;
+        const quality = typeof options.quality === "number" && Number.isFinite(options.quality) && options.quality > 0 && options.quality <= 1
+            ? options.quality
+            : DEFAULT_QUALITY;
+        const scale = Math.min(1, maxEdge / Math.max(bitmap.width, bitmap.height));
+        const width = Math.max(1, Math.round(bitmap.width * scale));
+        const height = Math.max(1, Math.round(bitmap.height * scale));
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        const context = canvas.getContext("2d");
+        if (!context)
+            throw new PhotoError("unreadable");
+        // JPEG has no alpha: an unfilled canvas would encode transparent pixels as black.
+        context.fillStyle = "#ffffff";
+        context.fillRect(0, 0, width, height);
+        context.drawImage(bitmap, 0, 0, width, height);
+        const encoded = await new Promise((resolve) => canvas.toBlob(resolve, "image/jpeg", quality));
+        // Release the backing store now: Safari caps total canvas memory, and a
+        // site may prepare several photos at once.
+        canvas.width = canvas.height = 0;
+        if (!encoded)
+            throw new PhotoError("unreadable");
+        blob = encoded;
+    }
+    catch (cause) {
+        // A raw DOMException from createElement, getContext, drawImage or toBlob
+        // still reaches the site as a PhotoError, so its message is always safe to show.
+        throw cause instanceof PhotoError ? cause : new PhotoError("unreadable", { cause });
+    }
+    finally {
+        bitmap.close();
+    }
+    if (blob.size > PHOTO_LIMITS.maxUploadBytes)
+        throw new PhotoError("too_large");
+    const base = file.name.replace(/\.[^.]*$/, "") || "photo";
+    return new File([blob], `${base}.jpg`, { type: "image/jpeg", lastModified: file.lastModified });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullgrainsoftware/portal",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Fullgrain Portal site SDK: manifest, typed content reader, sync CLI, preview bridge, commerce, inquiries and bookings clients",
   "repository": {
     "type": "git",