@12-apps/storage 1.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/storage",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "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": {
@@ -40,12 +40,12 @@
     }
   },
   "dependencies": {
-    "@12-apps/ui": "^4.0.1",
+    "@12-apps/ui": "^6.1.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.20.0",
-    "@12-apps/typescript-config": "^1.20.0",
+    "@12-apps/eslint-config": "^1.21.1",
+    "@12-apps/typescript-config": "^1.20.1",
     "@aws-sdk/client-s3": "^3.703.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",

package/src/react/failures.ts

@@ -58,6 +58,38 @@ export interface WebStorageMessages {
   session_expired: string;
   /** `fetch` rejected outright; no response ever arrived. */
   transport: string;
+
+  /**
+   * THE FIVE BELOW ARE THE REFUSALS THAT USED TO HAVE NO KNOB AT ALL.
+   *
+   * They are decided in the browser before a request leaves it (see
+   * {@link rejectFileUpfront}) or after a response nothing could parse, and they
+   * were written as literals inside those functions — not defaults a host could
+   * override, but sentences a host could not reach. The docstring at the top of
+   * this file already argued they should be here ("every sentence here reaches a
+   * store owner, so it is product copy"); these four simply never arrived.
+   *
+   * A host overriding `file_too_large` and finding its own words replaced two
+   * lines later by ours is the specific failure this closes.
+   *
+   * Three take the fact they are about, because the sentence is worthless
+   * without it: the size that was refused, the type that was refused. Functions
+   * rather than tokens in a string, so a host writing "8,4 MB é grande demais"
+   * can put the number where its own grammar wants it.
+   */
+
+  /** A 0-byte file — an interrupted copy or an unreadable share. */
+  empty_file: string;
+  /** Over the ceiling, before any request. Both sizes already formatted. */
+  file_too_large_upfront: (context: { size: string; limit: string }) => string;
+  /** The OS identified no type at all — an extensionless drop, most often. */
+  unknown_content_type: string;
+  /** A type we do not accept. Carries it, because the owner will dispute it. */
+  unsupported_content_type_upfront: (context: { contentType: string }) => string;
+  /** 2xx with no key in the body — accepted, and unusable. */
+  missing_key: string;
+  /** Anything thrown on the way. The last resort, and it says so. */
+  upload_failed: string;
 }
 
 /** Copy that only makes sense with the configured ceiling in it. */
@@ -82,16 +114,34 @@ export function defaultWebStorageMessages(
     not_found: 'Essa imagem não está mais disponível.',
     session_expired: 'Sua sessão expirou. Entre novamente e repita o envio.',
     transport: 'Não foi possível falar com o servidor. Verifique sua conexão e tente de novo.',
+    empty_file: 'Arquivo vazio (0 bytes). Escolha a imagem novamente.',
+    file_too_large_upfront: ({ size, limit }) =>
+      `Imagem muito grande: ${size}. O limite é ${limit} — reduza a imagem e tente de novo.`,
+    unknown_content_type:
+      'Não foi possível identificar o tipo do arquivo. Envie um PNG, JPG ou WebP.',
+    unsupported_content_type_upfront: ({ contentType }) =>
+      `Formato não suportado (${contentType}). Envie PNG, JPG, WebP ou GIF.`,
+    missing_key: 'O servidor aceitou a imagem mas não devolveu a chave. Tente de novo.',
+    upload_failed: 'Falha ao enviar a imagem. Tente de novo em instantes.',
   };
 }
 
-function resolve(
+/**
+ * The messages in force for a mount's ceiling.
+ *
+ * Exported because `use-upload` needs the same table for the two refusals it
+ * phrases itself, and a second `{ ...defaults, ...overrides }` there would be
+ * the exact drift this file exists to prevent.
+ */
+export function messagesOf(
   maxBytes: number,
-  overrides: Partial<WebStorageMessages> | undefined,
+  overrides?: Partial<WebStorageMessages>,
 ): WebStorageMessages {
   return { ...defaultWebStorageMessages({ limit: megabytes(maxBytes) }), ...overrides };
 }
 
+const resolve = messagesOf;
+
 /**
  * The sentence for a refusal CODE, or `undefined` for a code with no entry.
  *
@@ -101,7 +151,11 @@ function resolve(
  */
 function sentenceFor(messages: WebStorageMessages, code: string): string | undefined {
   if (!Object.prototype.hasOwnProperty.call(messages, code)) return undefined;
-  return messages[code as keyof WebStorageMessages];
+  const entry = messages[code as keyof WebStorageMessages];
+  // Only the plain-string entries are reachable by a server CODE. The three
+  // that take a fact are browser-side refusals with no server equivalent, and
+  // a response naming one would otherwise render a function at a store owner.
+  return typeof entry === 'string' ? entry : undefined;
 }
 
 /**
@@ -116,20 +170,26 @@ function sentenceFor(messages: WebStorageMessages, code: string): string | undef
  * extensionless drop, most often) — worth its own sentence, because "formato não
  * suportado" reads as an accusation about a file the owner knows is a PNG.
  */
-export function rejectFileUpfront(file: File, maxBytes: number): string | null {
+export function rejectFileUpfront(
+  file: File,
+  maxBytes: number,
+  overrides?: Partial<WebStorageMessages>,
+): string | null {
+  const messages = resolve(maxBytes, overrides);
   if (file.size === 0) {
-    return 'Arquivo vazio (0 bytes). Escolha a imagem novamente.';
+    return messages.empty_file;
   }
   if (file.size > maxBytes) {
-    return `Imagem muito grande: ${megabytes(file.size)}. O limite é ${megabytes(
-      maxBytes,
-    )} — reduza a imagem e tente de novo.`;
+    return messages.file_too_large_upfront({
+      size: megabytes(file.size),
+      limit: megabytes(maxBytes),
+    });
   }
   if (file.type === '') {
-    return 'Não foi possível identificar o tipo do arquivo. Envie um PNG, JPG ou WebP.';
+    return messages.unknown_content_type;
   }
   if (!ACCEPTED_CONTENT_TYPES.includes(file.type)) {
-    return `Formato não suportado (${file.type}). Envie PNG, JPG, WebP ou GIF.`;
+    return messages.unsupported_content_type_upfront({ contentType: file.type });
   }
   return null;
 }

package/src/react/use-upload.ts

@@ -2,6 +2,7 @@ import { useState } from 'react';
 
 import { STORAGE_PATHS } from '../paths';
 import {
+  messagesOf,
   rejectFileUpfront,
   transportFailure,
   uploadFailure,
@@ -87,7 +88,7 @@ export function useUpload(config: UseUploadConfig): UploadState {
     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.');
+      setError(messagesOf(config.maxBytes, config.messages).missing_key);
       return null;
     }
     return key;
@@ -103,14 +104,14 @@ export function useUpload(config: UseUploadConfig): UploadState {
       const upright =
         options.optimize === false ? file : await optimizeImage(file, config.profile);
 
-      const upfront = rejectFileUpfront(upright, config.maxBytes);
+      const upfront = rejectFileUpfront(upright, config.maxBytes, config.messages);
       if (upfront) {
         setError(upfront);
         return null;
       }
       return await send(upright);
     } catch {
-      setError('Falha ao enviar a imagem. Tente de novo em instantes.');
+      setError(messagesOf(config.maxBytes, config.messages).upload_failed);
       return null;
     } finally {
       setUploading(false);