@12-apps/storage 2.1.0 → 2.3.0

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@12-apps/storage",
-  "version": "2.1.0",
+  "version": "2.3.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": {
     ".": "./src/index.ts",
-    "./server": "./src/server/index.ts",
-    "./react": "./src/react/index.ts",
     "./hono": "./src/hono/index.ts",
+    "./manifest": "./src/manifest/index.ts",
+    "./manifest/server": "./src/manifest/server.ts",
+    "./package.json": "./package.json",
+    "./react": "./src/react/index.ts",
     "./s3": "./src/s3/index.ts",
-    "./package.json": "./package.json"
+    "./server": "./src/server/index.ts"
   },
   "scripts": {
     "clean": "rm -rf node_modules coverage",
@@ -20,6 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
+    "@12-apps/wiring": ">=1.9.0",
     "@aws-sdk/client-s3": ">=3.700.0",
     "hono": ">=4.0.0",
     "react": ">=19.0.0",
@@ -40,12 +43,13 @@
     }
   },
   "dependencies": {
-    "@12-apps/ui": "^6.2.0",
+    "@12-apps/ui": "^6.4.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
     "@12-apps/typescript-config": "^1.20.1",
+    "@12-apps/wiring": "^1.10.0",
     "@aws-sdk/client-s3": "^3.703.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",

package/src/manifest/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@12-apps/storage/manifest` — the SHARED wiring manifest.
+ *
+ * Identity and the runtime inventory. Three absences are deliberate rather
+ * than unfinished:
+ *
+ * - **No `db`.** This package owns no table. What an uploaded object leaves
+ *   behind is a KEY, and the row that key hangs off is the host's own — a
+ *   product image, a store logo — so there is nothing here to compose.
+ * - **No `env`.** `./server`'s own header states the rule this manifest would
+ *   otherwise have to restate: there are no `process.env` reads in shipped
+ *   source, because every deployment-shaped decision (the driver, the byte
+ *   ceiling, the key prefix, the bucket) is an ARGUMENT. A package that reads
+ *   the environment decides for its host; this one asks.
+ * - **No `web` inventory.** The React half is components a host renders, not
+ *   a mountable surface with its own routes.
+ *
+ * `observability` is mandatory here because `http` is: a refused upload or a
+ * driver that could not be reached files under `storage` rather than under
+ * whichever host happened to mount it.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):
+ * the manifests are plain `satisfies`-checked values, and the producer
+ * factories' runtime assertions run in this package's own test suite.
+ */
+
+import type { PackageManifest } from '@12-apps/wiring';
+
+export const storageManifest = {
+  name: '@12-apps/storage',
+  contract: 1,
+  observability: { namespace: 'storage' },
+  server: ['http'],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -0,0 +1,95 @@
+/**
+ * `@12-apps/storage/manifest/server` — the server capabilities.
+ *
+ * `http.create` wraps `createApiStorage` in a WIRE VIEW that finally makes the
+ * response rendering the PACKAGE's. `StorageRouteResponse` is a three-way
+ * union — a JSON answer, an object's bytes, or a redirect to where the object
+ * lives — and until now every host turned those three arms into a `Response`
+ * itself. That is mechanism, identical for every host, and one arm of it is
+ * a security detail rather than a formatting one:
+ *
+ *     const body = response.bytes.slice().buffer;
+ *
+ * The `.slice()` is load-bearing. A `Uint8Array` from Node is a view over a
+ * POOLED allocation, so handing `.buffer` straight to `Response` serves the
+ * client whatever else happens to share that pool. A host that re-derives this
+ * renderer has to know that; a host that binds this manifest does not.
+ *
+ * The bytes and redirect arms therefore answer the contract's RAW half
+ * (`{ response }`), which wiring 1.9.0 added for exactly this: answers
+ * `{ status, body }` cannot express — a stream, a redirect whose headers are
+ * the payload, bytes with their own content type.
+ */
+
+import type { AnyServerManifest, WireRequest, WireRouteAnswer } from '@12-apps/wiring';
+
+import {
+  createApiStorage,
+  type ApiStorage,
+  type ApiStorageConfig,
+  type StorageRoute,
+  type StorageRouteResponse,
+} from '../server';
+
+/** The descriptor's chosen answer, as the wiring contract carries it. */
+export function asWireAnswer(response: StorageRouteResponse): WireRouteAnswer {
+  if ('redirect' in response) {
+    return { response: Response.redirect(response.redirect, 302) };
+  }
+  if ('bytes' in response) {
+    // Its OWN ArrayBuffer — see the note above; a view over the pool leaks.
+    const body = response.bytes.slice().buffer as ArrayBuffer;
+    return {
+      response: new Response(body, {
+        status: response.status,
+        headers: {
+          ...response.headers,
+          'content-length': String(response.bytes.byteLength),
+        },
+      }),
+    };
+  }
+  return { status: response.status, body: response.body };
+}
+
+/** One `StorageRoute` as the wiring contract reads it. */
+function asWireRoute(route: StorageRoute): {
+  method: StorageRoute['method'];
+  path: string;
+  kind: 'authenticated' | 'public';
+  handle(request: WireRequest): Promise<WireRouteAnswer>;
+} {
+  return {
+    method: route.method,
+    path: route.path,
+    // The descriptor's own `auth` flag IS the contract's route kind: a
+    // `public` object read is anonymous by design, and the host's gates read
+    // this rather than a second table that could disagree with it.
+    kind: route.auth === 'public' ? 'public' : 'authenticated',
+    handle: async (request) => {
+      if (!request.request) {
+        throw new Error('@12-apps/storage needs the raw request — bind an adapter that forwards it.');
+      }
+      return asWireAnswer(
+        await route.handle({
+          actor: (request.actor ?? null) as Parameters<StorageRoute['handle']>[0]['actor'],
+          params: request.params,
+          request: request.request,
+        }),
+      );
+    },
+  };
+}
+
+/** `createApiStorage`, its routes re-shaped for the aggregate. */
+export function createWireApiStorage(
+  config: ApiStorageConfig,
+): Omit<ApiStorage, 'routes'> & { routes: ReturnType<typeof asWireRoute>[] } {
+  const api = createApiStorage(config);
+  return { ...api, routes: api.routes.map(asWireRoute) };
+}
+
+export const storageServerManifest = {
+  name: '@12-apps/storage',
+  http: { create: createWireApiStorage },
+} as const satisfies AnyServerManifest;

package/src/react/create-web-storage.tsx

@@ -85,6 +85,7 @@ export function createWebStorage(config: WebStorageConfig): WebStorage {
           value={imageKey}
           onChange={setImageKey}
           label={messages.fieldLabel}
+          removeLabel={messages.fieldRemove}
           helperText={messages.fieldHelper}
         />
       </Stack>

package/src/react/failures.ts

@@ -100,13 +100,15 @@ export interface WebStorageMessages {
   /**
    * The standalone upload page's own chrome — heading, the one-line
    * instruction (which carries the ceiling, same rule as the refusals), the
-   * field label and its helper. These rendered as literals inside
-   * `createWebStorage` until copy became required config.
+   * field label, its helper, and the button that clears a chosen image.
+   * These rendered as literals inside `createWebStorage` until copy became
+   * required config.
    */
   pageTitle: string;
   pageIntro: string;
   fieldLabel: string;
   fieldHelper: string;
+  fieldRemove: string;
 }
 
 /** Copy that only makes sense with the configured ceiling in it. */

package/src/react/image-field.tsx

@@ -34,7 +34,10 @@ export interface ImageFieldProps {
   previewUrl?: string | null;
   /** Called with the new key, or `null` when the image is removed. */
   onChange: (imageKey: string | null) => void;
-  label?: string;
+  /** The dropzone's own label. REQUIRED — this package ships no default copy. */
+  label: string;
+  /** The button that clears a chosen image. REQUIRED, for the same reason. */
+  removeLabel: string;
   helperText?: string;
   /** Passed through per upload — `{ optimize: false }` for a rendered canvas. */
   uploadOptions?: UploadOptions;
@@ -89,7 +92,7 @@ export function ImageField(props: BoundImageFieldProps): JSX.Element {
       ) : null}
       <UploadButton
         variant="dropzone"
-        label={props.label ?? 'Enviar imagem'}
+        label={props.label}
         accept={ACCEPT}
         disabled={props.disabled || uploader.uploading}
         uploading={uploader.uploading}
@@ -100,7 +103,7 @@ export function ImageField(props: BoundImageFieldProps): JSX.Element {
       {preview ? (
         <Box>
           <Button variant="text" onClick={handleRemove} dataTestId={`${testId}-remove`}>
-            Remover imagem
+            {props.removeLabel}
           </Button>
         </Box>
       ) : null}

package/src/react/pt-BR.ts

@@ -34,5 +34,6 @@ export function PT_BR_WEB_STORAGE_MESSAGES(
     pageIntro: `Envie um PNG, JPG, WebP ou GIF de até ${context.limit}.`,
     fieldLabel: 'Foto do produto',
     fieldHelper: 'A imagem é reduzida no navegador antes do envio.',
+    fieldRemove: 'Remover imagem',
   };
 }