@12-apps/storage 2.4.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/storage",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "type": "module",
   "description": "Image uploads that land at YOUR OWN ORIGIN, never at the bucket (12-20). Isomorphic core (format allowlist, upload ceiling, object-key grammar, rendition set, refusal taxonomy, wire schemas), host-mounted backend surface (./server: createApiStorage, the local-disk driver, the image-pipeline port, the orphan reclaim), Hono adapter (./hono), the S3-compatible driver behind its own subpath (./s3) and the bound picker + upload hook (./react). Standardized adoption contract in ADOPTING.md.",
   "exports": {
@@ -43,13 +43,14 @@
     }
   },
   "dependencies": {
-    "@12-apps/ui": "^6.8.0",
+    "@12-apps/ui": "^6.9.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
+    "@12-apps/i18n": "^1.1.0",
     "@12-apps/typescript-config": "^1.20.1",
-    "@12-apps/wiring": "^1.10.0",
+    "@12-apps/wiring": "^1.11.0",
     "@aws-sdk/client-s3": "^3.703.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",

package/src/en-US.ts

@@ -0,0 +1,30 @@
+import type { StorageMessageContext, StorageMessages } from './problems';
+
+/**
+ * The en-US pack — a NAMED factory a host passes by hand
+ * (`messages: EN_US_STORAGE_MESSAGES`), never a default. The filename is what
+ * exempts this file from the copy-portability gate, as `pt-BR.ts` beside it is
+ * exempt.
+ *
+ * `limit` is interpolated rather than hard-coded, for the reason the pt-BR pack
+ * gives: a host that raises `maxBytes` must not end up with a message naming
+ * the old number, which is the single commonest way this kind of copy goes
+ * stale. A translation that inlined the number would reintroduce exactly that.
+ */
+export function EN_US_STORAGE_MESSAGES(context: StorageMessageContext): StorageMessages {
+  return {
+    invalid_base64: 'That image is not correctly base64-encoded.',
+    empty_file: 'That image is empty.',
+    file_too_large: `That image is larger than the ${context.limit} limit.`,
+    content_mismatch:
+      'The image contents do not match the format you declared. Send a PNG, JPEG, WebP or GIF.',
+    unsupported_content_type: 'Unsupported format. Send a PNG, JPG, WebP or GIF.',
+    image_unreadable: 'That image could not be read — the file appears to be corrupted.',
+    image_dimensions_too_large: 'That image is too large in dimensions to process.',
+    storage_not_configured: 'Image storage has not been set up for this store yet.',
+    storage_unavailable: 'That image could not be saved right now. Try again in a moment.',
+  };
+}
+
+/** The 401 the mounted router answers when the host resolves no actor. */
+export const EN_US_STORAGE_UNAUTHENTICATED = 'Not authenticated.';

package/src/index.ts

@@ -76,6 +76,8 @@ export {
   type StorageProblem,
 } from './problems';
 export { PT_BR_STORAGE_MESSAGES, PT_BR_STORAGE_UNAUTHENTICATED } from './pt-BR';
+export { EN_US_STORAGE_MESSAGES, EN_US_STORAGE_UNAUTHENTICATED } from './en-US';
+export { STORAGE_MESSAGES, STORAGE_UNAUTHENTICATED } from './locales';
 
 export {
   imageSources,

package/src/locales.ts

@@ -0,0 +1,31 @@
+import { EN_US_STORAGE_MESSAGES, EN_US_STORAGE_UNAUTHENTICATED } from './en-US';
+import type { StorageMessageContext, StorageMessages } from './problems';
+import { PT_BR_STORAGE_MESSAGES, PT_BR_STORAGE_UNAUTHENTICATED } from './pt-BR';
+
+/**
+ * Both languages, keyed by tag — what a host hands to `@12-apps/i18n` when the
+ * reader's language is a property of the request rather than of the deployment.
+ *
+ * The pack holds FACTORIES rather than tables, because that is what this
+ * package's copy already is: `limit` is interpolated so a host that raises
+ * `maxBytes` cannot end up with a message naming the old number. `localeCopy`
+ * therefore hands back a factory, and the host calls it with its context:
+ *
+ * ```ts
+ * const messages = localeCopy(STORAGE_MESSAGES)({ locale })({ limit });
+ * ```
+ *
+ * `LocalePack` is mirrored here rather than imported so the package stays
+ * liftable into a repo that has never heard of `@12-apps/i18n`.
+ */
+type LocalePack<T> = { readonly 'pt-BR': T; readonly 'en-US': T };
+
+export const STORAGE_MESSAGES = {
+  'pt-BR': PT_BR_STORAGE_MESSAGES,
+  'en-US': EN_US_STORAGE_MESSAGES,
+} as const satisfies LocalePack<(context: StorageMessageContext) => StorageMessages>;
+
+export const STORAGE_UNAUTHENTICATED = {
+  'pt-BR': PT_BR_STORAGE_UNAUTHENTICATED,
+  'en-US': EN_US_STORAGE_UNAUTHENTICATED,
+} as const satisfies LocalePack<string>;

package/src/problems.ts

@@ -54,6 +54,15 @@ export type StorageMessages = Readonly<Record<StorageProblem, string>>;
 export interface StorageMessageContext {
   /** `8 MB`, already formatted. */
   limit: string;
+  /**
+   * The language to answer this caller in, as a BCP-47 tag.
+   *
+   * This field is why `messages` was already the right SHAPE: a factory called
+   * per refusal can answer per reader, where a value handed over at the mount
+   * cannot. Absent means the host's adapter populated nothing — a single
+   * -audience host — and the factory should then answer as it always did.
+   */
+  locale?: string;
 }
 
 /**

package/src/react/en-US.ts

@@ -0,0 +1,49 @@
+import type { WebStorageMessageContext, WebStorageMessages } from './failures';
+
+/**
+ * The en-US pack — a NAMED factory a host passes by hand, never a default.
+ * `limit` is interpolated for the same reason the server pack does it: a host
+ * that raises the ceiling must not end up with copy naming the old number.
+ */
+export function EN_US_WEB_STORAGE_MESSAGES(
+  context: WebStorageMessageContext,
+): WebStorageMessages {
+  return {
+    forbidden: 'Your account may not upload images for this store.',
+    unsupported_content_type: 'Unsupported format. Send a PNG, JPG, WebP or GIF.',
+    file_too_large: `That image is too large. The limit is ${context.limit}.`,
+    invalid_key: 'That image could not be found.',
+    not_found: 'That image is no longer available.',
+    session_expired: 'Your session has expired. Sign in again and repeat the upload.',
+    transport: 'Could not reach the server. Check your connection and try again.',
+    empty_file: 'Empty file (0 bytes). Pick the image again.',
+    file_too_large_upfront: ({ size, limit }) =>
+      `That image is too large: ${size}. The limit is ${limit} — shrink it and try again.`,
+    unknown_content_type: 'Could not identify the file type. Send a PNG, JPG or WebP.',
+    unsupported_content_type_upfront: ({ contentType }) =>
+      `Unsupported format (${contentType}). Send a PNG, JPG, WebP or GIF.`,
+    missing_key: 'The server accepted the image but returned no key. Try again.',
+    upload_failed_http: ({ status, detail }) =>
+      `Could not upload that image (HTTP ${status}${detail}). Try again in a moment.`,
+    upload_failed: 'Uploading that image failed. Try again in a moment.',
+
+    pageTitle: 'Store images',
+    pageIntro: `Send a PNG, JPG, WebP or GIF of up to ${context.limit}.`,
+    fieldLabel: 'Product photo',
+    fieldHelper: 'The image is resized in the browser before it is sent.',
+    fieldRemove: 'Remove image',
+    field: {
+      // `buttonLabel` is never read here — `ImageField` overrides it with
+      // `fieldLabel`. It is still answered, because the type is the whole of
+      // what `UploadButton` may render and a partial answer is not a pack.
+      buttonLabel: 'Product photo',
+      dropzoneHint: 'Drop the image here, or click to choose one',
+      dropzoneRole: (label) => `Image upload area. ${label}`,
+      uploading: 'Uploading…',
+      dropReady: 'Image ready to drop',
+      percentUploaded: (percent) => `${percent}% uploaded`,
+      uploadInProgress: (percent) => `Upload in progress: ${percent}%`,
+      errorAnnouncement: (message) => `Error: ${message}`,
+    },
+  };
+}

package/src/react/index.ts

@@ -42,3 +42,5 @@ export {
   type WebStorageMessages,
 } from './failures';
 export { PT_BR_WEB_STORAGE_MESSAGES } from './pt-BR';
+export { EN_US_WEB_STORAGE_MESSAGES } from './en-US';
+export { WEB_STORAGE_MESSAGES } from './locales';

package/src/react/locales.ts

@@ -0,0 +1,18 @@
+import { EN_US_WEB_STORAGE_MESSAGES } from './en-US';
+import type { WebStorageMessageContext, WebStorageMessages } from './failures';
+import { PT_BR_WEB_STORAGE_MESSAGES } from './pt-BR';
+
+/**
+ * Both languages of the browser half, keyed by tag. Factories, for the reason
+ * the server pack's docstring gives: the ceiling is interpolated so copy cannot
+ * name a limit the host has since changed.
+ *
+ * `LocalePack` is mirrored here rather than imported so the package stays
+ * liftable into a repo that has never heard of `@12-apps/i18n`.
+ */
+type LocalePack<T> = { readonly 'pt-BR': T; readonly 'en-US': T };
+
+export const WEB_STORAGE_MESSAGES = {
+  'pt-BR': PT_BR_WEB_STORAGE_MESSAGES,
+  'en-US': EN_US_WEB_STORAGE_MESSAGES,
+} as const satisfies LocalePack<(context: WebStorageMessageContext) => WebStorageMessages>;

package/src/server/create-api-storage.ts

@@ -172,11 +172,14 @@ const SILENT: StorageLogger = { error: () => undefined };
 export function createApiStorage(config: ApiStorageConfig): ApiStorage {
   const specs = config.renditions ?? CATALOG_RENDITIONS;
   const keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
-  const messages: StorageMessages = config.messages({ limit: megabytes(config.maxBytes) });
+  const limit = megabytes(config.maxBytes);
+  // A host write holds no request and no reader, so it takes the words resolved
+  // in the deployment's own language. The ROUTES resolve per caller instead —
+  // see `storageRoutes` below, which is handed the factory rather than this.
   const writeDeps: StoreImageDeps = {
     driver: config.driver,
     pipeline: config.imagePipeline,
-    messages,
+    messages: config.messages({ limit }),
     maxBytes: config.maxBytes,
     specs,
     keyPrefix,
@@ -192,7 +195,7 @@ export function createApiStorage(config: ApiStorageConfig): ApiStorage {
   const resolve = (key: string): string => config.driver.publicUrl(key);
 
   return {
-    routes: storageRoutes(writeDeps),
+    routes: storageRoutes({ ...writeDeps, messages: config.messages, limit }),
     limits: {
       maxBytes: config.maxBytes,
       maxBytesLabel: megabytes(config.maxBytes),

package/src/server/routes.ts

@@ -1,7 +1,7 @@
 import { CONTENT_TYPE_BY_EXTENSION, acceptedContentTypeOf } from '../content-types';
 import { parseObjectMemberKey } from '../keys';
 import { STORAGE_PATHS } from '../paths';
-import { isStorageProblem, type StorageMessages } from '../problems';
+import { isStorageProblem, type StorageMessageContext, type StorageMessages } from '../problems';
 import type { StorageDriver } from './driver';
 import { readBodyCapped } from './read-body';
 import { storeImage, type StoreImageDeps } from './store-image';
@@ -54,6 +54,12 @@ export interface StorageRouteContext {
   actor: StorageActor | null;
   params: Record<string, string | undefined>;
   request: Request;
+  /**
+   * The language to answer in — the same field `@12-apps/wiring`'s
+   * `WireRequest` carries, mirrored here because this surface builds its own
+   * context. Populated by the host's adapter; absent is not an error.
+   */
+  locale?: string;
 }
 
 /** A JSON answer, an object's bytes, or a redirect to where the object lives. */
@@ -76,9 +82,15 @@ export interface StorageRoute {
   handle(context: StorageRouteContext): Promise<StorageRouteResponse>;
 }
 
-interface RoutesDeps extends StoreImageDeps {
+interface RoutesDeps extends Omit<StoreImageDeps, "messages"> {
   driver: StorageDriver;
-  messages: StorageMessages;
+  /**
+   * The factory, unresolved, plus the limit it needs. Resolving into a value
+   * here is what would re-freeze the language into the mount — this object is
+   * built once, per process.
+   */
+  messages: (context: StorageMessageContext) => StorageMessages;
+  limit: string;
 }
 
 /** Keys are content-addressed (a uuid), so an object may be cached forever. */
@@ -96,9 +108,12 @@ async function handleUpload(
     // override it (`WebStorageMessages.forbidden`).
     return { status: 403, body: { error: 'forbidden' } };
   }
+  // Worded HERE, per request, from the tag the adapter put on the context —
+  // never at the mount, which ran once at boot.
+  const messages = deps.messages({ limit: deps.limit, locale: context.locale });
   const contentType = acceptedContentTypeOf(context.request.headers.get('content-type'));
   if (!contentType) {
-    return { status: 400, body: { error: deps.messages.unsupported_content_type } };
+    return { status: 400, body: { error: messages.unsupported_content_type } };
   }
   // Capped WHILE STREAMING, so an oversize body is refused without ever being
   // held whole in memory.
@@ -111,12 +126,12 @@ async function handleUpload(
     // "o limite é 8 MB": a ceiling nothing enforced, in the one package whose
     // headline claim is that there is exactly ONE number. The sentence is built
     // from this mount's `maxBytes` and carries this mount's `messages` overrides.
-    return { status: 413, body: { error: deps.messages.file_too_large } };
+    return { status: 413, body: { error: messages.file_too_large } };
   }
   try {
     // No byte check here: `storeImage` owns it, so the endpoint and a host write
     // holding raw bytes cannot disagree about whether it ran (see store-image.ts).
-    const imageKey = await storeImage(deps, { bytes, contentType, scope: actor.scope });
+    const imageKey = await storeImage({ ...deps, messages }, { bytes, contentType, scope: actor.scope });
     return { status: 200, body: { data: { imageKey } } };
   } catch (error) {
     // The write path speaks in StorageProblemError precisely so both entrances