@12-apps/storage 1.0.0

package/src/react/index.ts

@@ -0,0 +1,44 @@
+/**
+ * `@12-apps/storage/react` — the browser half.
+ *
+ * One factory, {@link createWebStorage}. Everything else exported here is a part
+ * of it that a host may legitimately want on its own: the hook for a bespoke
+ * affordance, the re-encode for a form that shrinks a file before doing something
+ * else with it, and the failure vocabulary for a host rendering its own messages.
+ *
+ * There is deliberately no export that uploads anywhere but this package's own
+ * endpoint on the app's own origin.
+ */
+
+export {
+  createWebStorage,
+  type WebStorage,
+  type WebStorageConfig,
+} from './create-web-storage';
+
+export { ImageField, type BoundImageFieldProps, type ImageFieldProps } from './image-field';
+
+export {
+  useUpload,
+  type UploadOptions,
+  type UploadState,
+  type UseUploadConfig,
+} from './use-upload';
+
+export {
+  CATALOG_IMAGE_PROFILE,
+  optimizeImage,
+  resetWebpSupportProbe,
+  scaledSize,
+  webpName,
+  type ImageProfile,
+} from './optimize-image';
+
+export {
+  defaultWebStorageMessages,
+  rejectFileUpfront,
+  transportFailure,
+  uploadFailure,
+  type WebStorageMessageContext,
+  type WebStorageMessages,
+} from './failures';

package/src/react/optimize-image.ts

@@ -0,0 +1,215 @@
+/**
+ * Shrink a picked image BEFORE it is uploaded.
+ *
+ * A store owner picks the photo their phone or their supplier gave them, and that
+ * is what used to reach the bucket byte for byte: catalog objects are routinely
+ * 1–2 MB PNGs at 2000px, served whole into a card ~165px wide. The buyer
+ * downloads a hundred times the pixels they can see, on a phone, on mobile data,
+ * before the first price is legible — which is the entire "images take forever to
+ * load" complaint.
+ *
+ * WHY IN THE BROWSER as well as on the server. Doing it here means the bytes never
+ * travel at full size at all, so the upload itself gets faster and the size cap
+ * stops rejecting photos that are perfectly usable once resized. It is the device
+ * that picked the file doing work it can do for free. The server-side pipeline is
+ * not a duplicate of this: it exists for callers that are not browsers.
+ *
+ * WHAT IT WILL NOT DO. Three deliberate pass-throughs, each returning the
+ * ORIGINAL file untouched rather than a worse one:
+ *
+ *   - **GIFs.** A canvas holds one frame, so re-encoding would silently turn an
+ *     animation into a still. Better large than broken.
+ *   - **Anything the browser cannot decode or encode.** Engines without
+ *     `createImageBitmap`, a corrupt file, a test environment with no canvas. The
+ *     upload must keep working: optimization is an improvement, never a
+ *     prerequisite — and never a new way for an upload to hang.
+ *   - **A result that is not actually smaller.** An already-optimized 40 KB WebP
+ *     can round-trip LARGER. The size comparison at the end is what makes this
+ *     safe to run unconditionally.
+ */
+
+/** How an image is re-encoded. */
+export interface ImageProfile {
+  /**
+   * Longest side, in pixels, of the uploaded image.
+   *
+   * Chosen against the largest box the photo is ever drawn into — a 4:3 hero on a
+   * desktop viewport, with 2× headroom — NOT against the card. Storing only what
+   * the card needs would make every zoom soft, and a zoom is exactly where
+   * somebody looks closely.
+   */
+  maxEdge: number;
+  /** WebP quality, 0–1. */
+  quality: number;
+}
+
+export const CATALOG_IMAGE_PROFILE: ImageProfile = { maxEdge: 1280, quality: 0.82 };
+
+/**
+ * Types worth re-encoding. GIF is absent on purpose (see the header), and so is
+ * anything outside the upload allowlist — an unrecognised type is the upload
+ * layer's rejection to report, not ours to mangle first.
+ */
+const OPTIMIZABLE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
+
+/**
+ * Refuse to even DECODE beyond this. Decoding allocates width × height × 4 bytes
+ * of bitmap, so a hostile or accidental 100 MB file is a tab crash rather than a
+ * slow upload. Past this the file falls through untouched and the upload layer's
+ * own cap rejects it with a message that names the size.
+ */
+const DECODE_CEILING_BYTES = 32 * 1024 * 1024;
+
+/** Target box for `maxEdge`, preserving aspect ratio. Never enlarges. */
+export function scaledSize(
+  width: number,
+  height: number,
+  maxEdge: number,
+): { width: number; height: number } {
+  const longest = Math.max(width, height);
+  if (longest <= maxEdge) return { width, height };
+  const ratio = maxEdge / longest;
+  // At least 1px on the short side: a 4000×3 panorama would otherwise scale to a
+  // zero-height canvas, and `drawImage` onto one throws.
+  return {
+    width: Math.max(1, Math.round(width * ratio)),
+    height: Math.max(1, Math.round(height * ratio)),
+  };
+}
+
+/** `photo.png` → `photo.webp`; a name with no extension simply gains one. */
+export function webpName(name: string): string {
+  return `${name.replace(/\.[^.]+$/, '')}.webp`;
+}
+
+/** Whether this browser's canvas can actually emit WebP. Probed once. */
+let webpSupport: boolean | null = null;
+
+function canEncodeWebp(): boolean {
+  if (webpSupport !== null) return webpSupport;
+  try {
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    // `toDataURL` with an unsupported type does not throw — it silently answers a
+    // PNG data URL. Reading the prefix back is the only honest probe, and it is
+    // the same trap `toBlob` sets: it would hand back a PNG labelled WebP.
+    webpSupport = canvas.toDataURL('image/webp').startsWith('data:image/webp');
+  } catch {
+    webpSupport = false;
+  }
+  return webpSupport;
+}
+
+/** Reset the cached probe. Tests only — a real browser's answer never changes. */
+export function resetWebpSupportProbe(): void {
+  webpSupport = null;
+}
+
+/**
+ * Decode the file, or `null` if this environment cannot.
+ *
+ * `createImageBitmap` ONLY, deliberately. An `<img>` element whose `onload` and
+ * `onerror` BOTH stay silent is a real state — and the one jsdom is permanently in
+ * — which would leave this awaiting a promise that never settles, taking the
+ * upload with it. Trading an unbounded hang for "no optimization on an old
+ * browser" is not a close call. Decoding off the main thread is also the whole
+ * point on the phone this runs on.
+ */
+async function decode(file: File): Promise<ImageBitmap | null> {
+  if (typeof createImageBitmap !== 'function') return null;
+  try {
+    return await createImageBitmap(file);
+  } catch {
+    // A corrupt file, or a format this decoder will not take. Either way the
+    // upload proceeds with exactly the bytes the owner picked.
+    return null;
+  }
+}
+
+/**
+ * Draw `source` into a `target`-sized canvas and encode it.
+ *
+ * The canvas is left TRANSPARENT rather than filled: the bottle-on-white PNGs this
+ * exists for carry an alpha channel, and WebP keeps it. That is also why the
+ * non-WebP fallback re-encodes to the SOURCE type instead of to JPEG — a JPEG has
+ * no alpha, so "optimizing" a cut-out product photo that way would hand the
+ * storefront a black rectangle behind every bottle.
+ */
+async function encode(
+  source: ImageBitmap,
+  target: { width: number; height: number },
+  profile: ImageProfile,
+  sourceType: string,
+): Promise<Blob | null> {
+  // Probed BEFORE the drawing canvas exists: the probe allocates a canvas of its
+  // own, and interleaving the two makes the order they are created in part of this
+  // function's observable behaviour for no benefit.
+  const type = canEncodeWebp() ? 'image/webp' : sourceType;
+
+  const canvas = document.createElement('canvas');
+  canvas.width = target.width;
+  canvas.height = target.height;
+  const context = canvas.getContext('2d');
+  if (!context) return null;
+  context.imageSmoothingEnabled = true;
+  context.imageSmoothingQuality = 'high';
+  context.drawImage(source, 0, 0, target.width, target.height);
+
+  return new Promise((resolve) => {
+    if (typeof canvas.toBlob !== 'function') {
+      resolve(null);
+      return;
+    }
+    canvas.toBlob((blob) => resolve(blob), type, profile.quality);
+  });
+}
+
+/**
+ * Wrap an encoded blob as the file to upload, or `null` when it is not worth
+ * swapping in.
+ *
+ * `>=` and not `>`: a tie is no reason to trade a known-good original for a
+ * re-encode, and it keeps an already-optimal upload byte-identical. The rename is
+ * not cosmetic either — the server stores the object under the type this file
+ * declares.
+ */
+function asImprovedFile(blob: Blob | null, original: File): File | null {
+  if (!blob || blob.size >= original.size) return null;
+  const type = blob.type || original.type;
+  const name = type === 'image/webp' ? webpName(original.name) : original.name;
+  return new File([blob], name, { type, lastModified: original.lastModified });
+}
+
+/**
+ * A smaller, web-ready version of `file` — or `file` itself when that is not
+ * possible or not an improvement.
+ *
+ * Never throws and never rejects: every failure mode degrades to the original
+ * file, so a caller can await it unconditionally.
+ */
+export async function optimizeImage(
+  file: File,
+  profile: ImageProfile = CATALOG_IMAGE_PROFILE,
+): Promise<File> {
+  if (!OPTIMIZABLE_TYPES.has(file.type) || file.size > DECODE_CEILING_BYTES) return file;
+
+  const source = await decode(file);
+  if (!source) return file;
+
+  try {
+    const { width, height } = source;
+    if (width === 0 || height === 0) return file;
+    const target = scaledSize(width, height, profile.maxEdge);
+    const blob = await encode(source, target, profile, file.type);
+    return asImprovedFile(blob, file) ?? file;
+  } catch {
+    // Any surprise from canvas/drawImage — a tainted source, an out-of-memory
+    // allocation — leaves the upload with the file the owner actually picked.
+    return file;
+  } finally {
+    // Frees the decoded bitmap immediately rather than at the next GC — on a phone
+    // a 4000×3000 photo is 48 MB of it.
+    source.close();
+  }
+}

package/src/react/use-upload.ts

@@ -0,0 +1,121 @@
+import { useState } from 'react';
+
+import { STORAGE_PATHS } from '../paths';
+import {
+  rejectFileUpfront,
+  transportFailure,
+  uploadFailure,
+  type WebStorageMessages,
+} from './failures';
+import { optimizeImage, type ImageProfile } from './optimize-image';
+
+/**
+ * Storing an image from the browser: ONE request, to the package's own endpoint,
+ * which answers with the key to save.
+ *
+ * It is one request rather than two — and never a presigned bucket URL — for the
+ * reasons the root entry states at length: a key minted before the bytes exist has
+ * to PREDICT whether crops will accompany it, and a cross-origin PUT fails
+ * invisibly server-side and unfixably for the store owner. Neither is a trade this
+ * hook is allowed to reopen; there is no `presign` option.
+ *
+ * Every exit path that returns `null` sets a SPECIFIC `error` first — the file was
+ * too big, the session expired, the server could not read the image, the
+ * connection never landed. That is the difference between an owner who can fix
+ * their upload (or hand support a real symptom) and one staring at a red box that
+ * says only that something went wrong.
+ */
+
+/** Per-call knobs. Everything else about an upload is the same every time. */
+export interface UploadOptions {
+  /**
+   * Re-encode and downscale before sending (default `true`).
+   *
+   * Turned OFF for files that are not a picked photo — an app icon rendered to
+   * exactly 192 and 512 px, say, whose manifest declares `image/png` in a literal.
+   * Quietly handing that a WebP makes the manifest describe an asset that does not
+   * exist, and takes the app's installability with it.
+   */
+  optimize?: boolean;
+}
+
+export interface UploadState {
+  upload: (file: File, options?: UploadOptions) => Promise<string | null>;
+  uploading: boolean;
+  error: string | null;
+  clearError: () => void;
+}
+
+export interface UseUploadConfig {
+  /** Where the router is mounted, e.g. `/api`. */
+  apiBase: string;
+  /** The ceiling the SERVER enforces. The check here is only an early refusal. */
+  maxBytes: number;
+  /** The browser-side re-encode profile. */
+  profile?: ImageProfile;
+  /** How the request is made. Default: same-origin `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** pt-BR refusal copy overrides, for the codes only the host can explain. */
+  messages?: Partial<WebStorageMessages>;
+}
+
+export function useUpload(config: UseUploadConfig): UploadState {
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const endpoint = `${config.apiBase.replace(/\/$/, '')}${STORAGE_PATHS.upload}`;
+
+  async function send(file: File): Promise<string | null> {
+    const request = config.fetchImpl ?? fetch;
+    let response: Response;
+    try {
+      response = await request(endpoint, {
+        method: 'POST',
+        // The raw file, not base64 or multipart: the server reads the bytes
+        // straight off the stream against its own cap, and the type it stores the
+        // object as is this header.
+        headers: { 'content-type': file.type },
+        body: file,
+      });
+    } catch {
+      setError(transportFailure(config.messages));
+      return null;
+    }
+    if (!response.ok) {
+      setError(await uploadFailure(response, config.maxBytes, config.messages));
+      return null;
+    }
+    const payload = (await response.json()) as { data?: { imageKey?: string } };
+    const key = payload.data?.imageKey;
+    if (!key) {
+      setError('O servidor aceitou a imagem mas não devolveu a chave. Tente de novo.');
+      return null;
+    }
+    return key;
+  }
+
+  async function upload(file: File, options: UploadOptions = {}): Promise<string | null> {
+    setUploading(true);
+    setError(null);
+    try {
+      // Shrink FIRST, then validate — the order is the point (see
+      // `rejectFileUpfront`). `optimizeImage` never throws and returns the original
+      // when it cannot help, so the checks below still see a real file either way.
+      const upright =
+        options.optimize === false ? file : await optimizeImage(file, config.profile);
+
+      const upfront = rejectFileUpfront(upright, config.maxBytes);
+      if (upfront) {
+        setError(upfront);
+        return null;
+      }
+      return await send(upright);
+    } catch {
+      setError('Falha ao enviar a imagem. Tente de novo em instantes.');
+      return null;
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  return { upload, uploading, error, clearError: () => setError(null) };
+}

package/src/renditions.ts

@@ -0,0 +1,71 @@
+/**
+ * The DERIVED sizes of a stored photo — the crops a storefront actually draws,
+ * cut once at upload instead of by every visitor's browser.
+ *
+ * Downscaling the uncropped object fixes the MEGABYTE. It does not fix the
+ * FRAMING, and the framing is what a buyer sees: a card's media block is a 4:3
+ * box, a supplier's photo is a 600×1200 bottle on white, and drawn `contain`
+ * the bottle occupies a third of the box with two flat columns beside it. The
+ * other half of the same waste is the byte — a 4:3 hero and a 64px thumbnail
+ * both served that one 1280px object.
+ *
+ * So an upload writes a SET:
+ *
+ *   <prefix>/<scope>/<uuid>/full.webp        the whole picture, uncropped
+ *   <prefix>/<scope>/<uuid>/card-320.webp    4:3, one card on a phone
+ *   <prefix>/<scope>/<uuid>/card-640.webp    4:3, a retina card / phone hero
+ *   <prefix>/<scope>/<uuid>/card-1280.webp   4:3, a retina hero on a desktop
+ *   <prefix>/<scope>/<uuid>/thumb-128.webp   1:1, a 64px row thumbnail
+ *   <prefix>/<scope>/<uuid>/thumb-256.webp   1:1, the same row at 2×
+ *
+ * ONE 4:3 FAMILY SERVES BOTH the card and the hero, because both draw a 4:3
+ * box. Three widths plus a `sizes` attribute is how "mobile and desktop" is
+ * expressed on the web; cutting a `detail-640` next to an identical `card-640`
+ * would double the objects to say the same thing.
+ *
+ * The list is in ONE place so the writer, the URL builder and the reclaimer
+ * cannot disagree about what exists.
+ */
+
+/** Which `srcset` family a size belongs to. */
+export type RenditionFamily = 'card' | 'thumb';
+
+/** One derived size: the object's name suffix and the exact canvas it fills. */
+export interface RenditionSpec {
+  /** File stem — the key is `<set>/<name>.webp`. */
+  name: string;
+  width: number;
+  height: number;
+  family: RenditionFamily;
+}
+
+/**
+ * The default rendition set.
+ *
+ * The widths are drawn sizes at 1× and 2×: a card is ~165–250 CSS px, a hero is
+ * the modal's full width (~390 on a phone, ~600 on a desktop), and a row
+ * thumbnail is 64. A host that draws different boxes passes its own list.
+ */
+export const CATALOG_RENDITIONS: readonly RenditionSpec[] = [
+  { name: 'card-320', width: 320, height: 240, family: 'card' },
+  { name: 'card-640', width: 640, height: 480, family: 'card' },
+  { name: 'card-1280', width: 1280, height: 960, family: 'card' },
+  { name: 'thumb-128', width: 128, height: 128, family: 'thumb' },
+  { name: 'thumb-256', width: 256, height: 256, family: 'thumb' },
+];
+
+/** Every rendition is WebP, whatever the source was. */
+export const RENDITION_CONTENT_TYPE = 'image/webp';
+
+/** A cut rendition: which spec it satisfies and the bytes to store. */
+export interface RenditionOutput {
+  spec: RenditionSpec;
+  bytes: Uint8Array;
+}
+
+/** The distinct families in a rendition list, in first-seen order. */
+export function renditionFamilies(
+  specs: readonly RenditionSpec[],
+): readonly RenditionFamily[] {
+  return [...new Set(specs.map((spec) => spec.family))];
+}

package/src/s3/index.ts

@@ -0,0 +1,105 @@
+import { DeleteObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+
+import { StorageNotConfiguredError } from '../problems';
+import type { StorageDriver } from '../server/driver';
+import {
+  assertRemoteUrlConfig,
+  remoteObjectUrl,
+  type RemoteObjectUrlConfig,
+} from '../server/remote-url';
+
+/**
+ * `@12-apps/storage/s3` — objects in an S3-compatible bucket.
+ *
+ * Behind its own subpath with `@aws-sdk/client-s3` as an OPTIONAL peer, so a host
+ * on local disk never resolves the SDK. `./server` deliberately does not
+ * re-export this.
+ *
+ * ONE driver covers every S3-compatible vendor. AWS needs a `region`; DigitalOcean
+ * Spaces, MinIO, R2 and the rest need an `endpoint`, plus `forcePathStyle` for the
+ * ones that cannot do virtual-hosted addressing. A second vendor is therefore a
+ * config entry and nothing else — no branch in the upload path, and no host code.
+ *
+ * Nothing here reads `process.env`. The credentials a deployment holds are the
+ * deployment's business, and a package that read them would silently pick up
+ * whatever happened to be exported in a test.
+ */
+
+export interface S3DriverConfig extends RemoteObjectUrlConfig {
+  /** Explicit credentials. Omit to use the SDK's default chain (IAM role, …). */
+  credentials?: { accessKeyId: string; secretAccessKey: string };
+  /**
+   * Canned ACL for stored objects. `public-read` by default, because an object is
+   * loaded straight by an `<img>` with no bucket policy — and a private object
+   * behind a public URL 403s for every visitor while the upload reports success.
+   *
+   * `undefined` for a bucket with `BucketOwnerEnforced`, which rejects ANY ACL
+   * header; such a bucket needs a policy or a CDN in front of it instead.
+   */
+  acl?: 'private' | 'public-read' | undefined;
+}
+
+function buildClient(config: S3DriverConfig): S3Client {
+  return new S3Client({
+    ...(config.region ? { region: config.region } : {}),
+    ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+    ...(config.forcePathStyle ? { forcePathStyle: true } : {}),
+    ...(config.credentials ? { credentials: config.credentials } : {}),
+    // Do NOT compute an integrity checksum unless the operation requires one.
+    // Since v3.729 the SDK adds a CRC32 by default; for a PRESIGNED PUT it is
+    // computed over a body that is empty at signing time and then hoisted into the
+    // URL, so a store that validates it rejects the upload for a digest mismatch
+    // on bytes the signer never saw. This package never presigns, but the setting
+    // is kept as a matter of record: it is the trap that made "the bytes go
+    // through the server" the only shape here.
+    requestChecksumCalculation: 'WHEN_REQUIRED',
+  });
+}
+
+/**
+ * Objects in a bucket, written by the app server with credentials it already
+ * holds. There is no method that hands a browser an address — see the root
+ * entry for why that is the whole point.
+ */
+export function createS3Driver(config: S3DriverConfig): StorageDriver {
+  // At construction, not at the first upload: an operator finds out from a boot
+  // failure rather than from a store owner whose photo would not save.
+  assertRemoteUrlConfig(config);
+  const acl = 'acl' in config ? config.acl : 'public-read';
+  let client: S3Client | undefined;
+  // Built lazily and cached: endpoint resolution and the credential chain are not
+  // free per call, and a host that only ever reads URLs never pays for either.
+  const send = (command: PutObjectCommand | DeleteObjectCommand): Promise<unknown> => {
+    client ??= buildClient(config);
+    return client.send(command);
+  };
+
+  return {
+    name: config.endpoint ? 's3-compatible' : 's3',
+    put: async (key, bytes, contentType) => {
+      if (!config.bucket) {
+        throw new StorageNotConfiguredError('Storing an object needs a bucket.');
+      }
+      await send(
+        new PutObjectCommand({
+          Bucket: config.bucket,
+          Key: key,
+          Body: bytes,
+          ContentType: contentType,
+          // A real request header, which the SDK signs. Passing `x-amz-acl` as a
+          // presigned QUERY parameter is accepted and then silently ignored — the
+          // object stores private behind a public URL.
+          ...(acl ? { ACL: acl } : {}),
+        }),
+      );
+    },
+    // S3's DeleteObject is idempotent — removing a key that is not there answers
+    // 204, not an error — which is exactly the contract the port advertises.
+    delete: async (key) => {
+      await send(new DeleteObjectCommand({ Bucket: config.bucket, Key: key }));
+    },
+    publicUrl: (key) => remoteObjectUrl(config, key),
+    // No `read`: the bytes are in the bucket, so the serve route redirects to
+    // their public URL instead of streaming them through the app server.
+  };
+}