@endora-commerce/mod-assets-library 0.0.0-stage → 0.100.0

package/dist/migrations/index.js

@@ -0,0 +1,29 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260505T102206AssetsLibraryInit } from './20260505T102206_assets_library_init.js';
+export const migrations = [
+    Migration20260505T102206AssetsLibraryInit,
+];
+export { Migration20260505T102206AssetsLibraryInit, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,yCAAyC,EAAE,MAAM,0CAA0C,CAAC;AAErG,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,yCAAyC;CAC1C,CAAC;AAEF,OAAO,EACL,yCAAyC,GAC1C,CAAC"}

package/docs/assets-library/index.md

@@ -0,0 +1,125 @@
+---
+title: Assets Library
+description: Central digital-asset library with pluggable storage adapters, soft-delete, and reference-protection guards
+---
+
+# Assets Library
+
+The Assets Library is the platform's digital-asset substrate. It owns:
+
+- A central catalogue of files (images, video, PDFs, documents) reusable
+  across Product media, Product attachments, Category main images, and CMS
+  pages.
+- A folder tree for organising assets.
+- Pluggable storage backends — Local filesystem, Amazon S3, GCP Cloud
+  Storage — configured from Settings, exactly one active at a time.
+- Public/private visibility per asset.
+- Reference protection: assets in use by Catalog or CMS cannot be deleted
+  until every reference is detached.
+
+## Quick start
+
+1. **Active adapter** — open Settings → Storage and pick one of `local`, `s3`,
+   or `gcs`. Defaults to `local`.
+2. **Local FS** — set `assets.local.base_dir` (default `var/assets`). The
+   admin server creates the directory tree at upload time. Set
+   `assets.local.public_url_base` if the backend is fronted by a different
+   public hostname (e.g. a CDN or a reverse proxy); leave it blank and every
+   URL is built on this deployment's public API origin instead.
+3. **Amazon S3** — set `assets.s3.bucket`, `assets.s3.region`,
+   `assets.s3.access_key_id`, `assets.s3.secret_access_key`. Optional:
+   `assets.s3.endpoint` (for S3-compatible providers like MinIO),
+   `assets.s3.prefix`, `assets.s3.public_base_url` (CDN base URL prefix).
+4. **GCP Cloud Storage** — set `assets.gcs.bucket` and either
+   `assets.gcs.service_account_json` (paste the full JSON) or rely on
+   ambient credentials. Optional: `assets.gcs.prefix`,
+   `assets.gcs.public_base_url`.
+5. **Test the connection** — `POST /api/v1/admin/assets/storage/self-check`.
+   Returns `{ ok: true }` on success or `{ ok: false, reason: ... }` on
+   misconfiguration. The dashboard is at `GET /api/v1/admin/assets/storage/state`.
+
+## Upload constraints
+
+Two settings gate uploads, both checked before any byte reaches the active
+adapter:
+
+- `assets.allowed_file_types` — list of file extensions or MIME types
+  (e.g. `["jpg", "png", "image/jpeg", "application/pdf"]`). The sentinel
+  `["*"]` (default) disables the gate. Wildcards like `image/*` match any
+  MIME under that prefix. The check considers both the declared MIME and
+  the magic-number-sniffed MIME (file-type) and rejects when either fails.
+- `assets.max_file_size_mb` — integer cap in MB. `0` (default) disables
+  the cap.
+
+## Visibility & private URLs
+
+Each asset has `visibility ∈ {public, private}`. Public URLs are stable;
+private URLs are short-lived (TTL = `assets.private_url_ttl_sec`, default
+300s) and re-issued by the admin or storefront on every read.
+
+For the **local FS** adapter, private URLs are HMAC-signed by the backend.
+The signing key is sourced from the `ASSETS_LIBRARY_HMAC_KEY` env var
+(generate with `openssl rand -hex 32`); rotate to invalidate every
+outstanding private URL.
+
+For **S3** and **GCS**, private URLs are V4-signed through the vendor SDK;
+nothing in the backend needs to be configured beyond the credentials.
+
+## Soft-delete & hard-delete
+
+Deletes go through a two-step lifecycle:
+
+1. `DELETE /api/v1/admin/assets/:id` → soft-delete. Sets `deletedAt` and
+   `purgeAfterAt = now + assets.soft_delete_retention_days` (default 30).
+   The asset disappears from listings and pickers but remains recoverable
+   via `POST /api/v1/admin/assets/:id/restore`.
+2. The repeating `HardDeleteAssetWorker` finalises after `purgeAfterAt`:
+   removes the row and asks the adapter to delete the underlying file.
+   If the backend cannot remove the file (read-only mount, revoked
+   credentials, network partition), the row stays and `pendingCleanup` is
+   set to `true`; the worker retries on the next tick.
+
+## Reference protection {#asset-reference-registry}
+
+Soft-delete is rejected with `409 ASSET_REFERENCED` when any of the
+following points at the asset:
+
+- `gallery_items.asset_id` (Product gallery)
+- `product_attachments.asset_id` (Product attachments)
+- `products.download_asset_id` (virtual-download products)
+- `categories.main_image_asset_id` (Category main image)
+- `cms_pages.body` containing a `{ type: "asset_ref", assetId }` node
+
+The reference list is included in the error envelope's `details` array so
+the admin UI can show "in use by" prompts.
+
+## Pluggable storage adapters
+
+Each backend implements the `StorageAdapter` SPI in
+`packages/modules/assets_library/src/backend/services/storage/`. Adding a fourth
+backend (Azure Blob, Backblaze B2, …) is a matter of dropping in a new
+class that implements:
+
+```ts
+selfCheck(): Promise<{ ok: boolean; reason?: string }>;
+newLocator({ assetId, originalFilename }): string;
+put({ locator, mimeType, visibility, stream, sizeBytes }): Promise<void>;
+resolveUrl({ locator, visibility, ttlSec? }): Promise<{ url; expiresAt }>;
+open({ locator }): Promise<NodeJS.ReadableStream>;
+delete({ locator }): Promise<void>;
+setVisibility?({ locator, visibility }): Promise<void>;
+```
+
+…and registering it in `AdapterRegistry.build`. See the existing
+`LocalFsStorageAdapter`, `S3StorageAdapter`, and `GcsStorageAdapter` for
+templates.
+
+## Legacy escape hatch
+
+Pre-existing `assets` rows whose `storage_url` was a URL this platform did not
+issue are tagged `storage_backend = 'legacy'` at migration time. The legacy
+resolver returns the URL verbatim for `public` assets — rebasing it onto the
+public API origin when the stored value is host-relative — and refuses to flip
+them to `private` (we cannot sign URLs we didn't issue), which surfaces as
+`409 ASSET_LEGACY_LOCATOR_CANNOT_HARDEN` to the admin. Re-upload through
+the active adapter to upgrade.

package/i18n/en.json

@@ -0,0 +1,54 @@
+{
+  "errors.ASSET_NOT_FOUND": "Asset Not Found.",
+  "errors.ASSET_REFERENCED": "Asset Referenced.",
+  "errors.ASSET_FOLDER_NOT_FOUND": "Asset Folder Not Found.",
+  "errors.ASSET_FOLDER_NOT_EMPTY": "Asset Folder Not Empty.",
+  "errors.ASSET_FOLDER_NAME_CONFLICT": "Asset Folder Name Conflict.",
+  "errors.ASSET_FOLDER_CYCLE": "Asset Folder Cycle.",
+  "errors.ASSET_UPLOAD_NO_FILE": "Asset Upload No File.",
+  "errors.ASSET_UPLOAD_TYPE_NOT_ALLOWED": "Asset Upload Type Not Allowed.",
+  "errors.ASSET_UPLOAD_TOO_LARGE": "Asset Upload Too Large.",
+  "errors.ASSET_STORAGE_UNAVAILABLE": "Asset Storage Unavailable.",
+  "errors.ASSET_STORAGE_MISCONFIGURED": "Asset Storage Misconfigured.",
+  "errors.ASSET_LEGACY_LOCATOR_CANNOT_HARDEN": "Asset Legacy Locator Cannot Harden.",
+  "errors.ASSET_FILE_MISSING": "Asset File Missing.",
+  "errors.ASSET_GONE": "Asset Gone.",
+  "errors.ASSET_ACCESS_DENIED": "Asset Access Denied.",
+  "common.search": "Search",
+  "common.loading": "Loading…",
+  "common.save": "Save",
+  "common.optional": "(optional)",
+  "common.ok": "OK",
+  "common.cancel": "Cancel",
+  "common.delete": "Delete",
+  "page.title": "Assets Library",
+  "page.description": "Upload, organize, and reuse images, videos, PDFs, and other files across the platform.",
+  "assets.title": "Assets",
+  "assets.searchPlaceholder": "Search filename or label…",
+  "assets.emptyFolder": "No assets in this folder yet.",
+  "assets.loadMore": "Load more",
+  "uploader.triggerCurrentFolder": "Upload to current folder",
+  "detail.title": "Asset detail",
+  "detail.openFile": "Open file",
+  "detail.filename": "Filename",
+  "detail.label": "Label (storefront)",
+  "detail.mimeType": "MIME type",
+  "detail.visibility": "Visibility",
+  "detail.storage": "Storage",
+  "detail.size": "Size",
+  "detail.bytes": "bytes",
+  "detail.referencedBy": "Referenced by",
+  "detail.notReferenced": "Not referenced.",
+  "detail.softDeleteTitle": "Soft-delete this asset",
+  "detail.softDeleteBlockedTitle": "Remove every reference first",
+  "detail.softDelete": "Soft-delete",
+  "visibility.public": "public",
+  "visibility.private": "private",
+  "folders.title": "Folders",
+  "folders.root": "Unsorted (root)",
+  "folders.namePlaceholder": "Folder name",
+  "folders.newSubfolder": "New sub-folder",
+  "folders.deleteConfirm": "Delete this folder?\n\nOK = move its contents to the parent folder, then delete.\nCancel = abort.",
+  "folders.removed": "Folder removed ({id}).",
+  "nav.assetsLibrary.label": "Assets library"
+}

package/i18n/pl.json

@@ -0,0 +1,54 @@
+{
+  "errors.ASSET_NOT_FOUND": "Błąd: asset not found.",
+  "errors.ASSET_REFERENCED": "Błąd: asset referenced.",
+  "errors.ASSET_FOLDER_NOT_FOUND": "Błąd: asset folder not found.",
+  "errors.ASSET_FOLDER_NOT_EMPTY": "Błąd: asset folder not empty.",
+  "errors.ASSET_FOLDER_NAME_CONFLICT": "Błąd: asset folder name conflict.",
+  "errors.ASSET_FOLDER_CYCLE": "Błąd: asset folder cycle.",
+  "errors.ASSET_UPLOAD_NO_FILE": "Błąd: asset upload no file.",
+  "errors.ASSET_UPLOAD_TYPE_NOT_ALLOWED": "Błąd: asset upload type not allowed.",
+  "errors.ASSET_UPLOAD_TOO_LARGE": "Błąd: asset upload too large.",
+  "errors.ASSET_STORAGE_UNAVAILABLE": "Błąd: asset storage unavailable.",
+  "errors.ASSET_STORAGE_MISCONFIGURED": "Błąd: asset storage misconfigured.",
+  "errors.ASSET_LEGACY_LOCATOR_CANNOT_HARDEN": "Błąd: asset legacy locator cannot harden.",
+  "errors.ASSET_FILE_MISSING": "Błąd: asset file missing.",
+  "errors.ASSET_GONE": "Błąd: asset gone.",
+  "errors.ASSET_ACCESS_DENIED": "Błąd: asset access denied.",
+  "common.search": "Szukaj",
+  "common.loading": "Wczytywanie…",
+  "common.save": "Zapisz",
+  "common.optional": "(opcjonalnie)",
+  "common.ok": "OK",
+  "common.cancel": "Anuluj",
+  "common.delete": "Usuń",
+  "page.title": "Biblioteka zasobów",
+  "page.description": "Przesyłaj, porządkuj i wykorzystuj ponownie obrazy, filmy, PDF-y oraz inne pliki na platformie.",
+  "assets.title": "Zasoby",
+  "assets.searchPlaceholder": "Szukaj po nazwie pliku lub etykiecie…",
+  "assets.emptyFolder": "W tym folderze nie ma jeszcze zasobów.",
+  "assets.loadMore": "Wczytaj więcej",
+  "uploader.triggerCurrentFolder": "Prześlij do bieżącego folderu",
+  "detail.title": "Szczegóły zasobu",
+  "detail.openFile": "Otwórz plik",
+  "detail.filename": "Nazwa pliku",
+  "detail.label": "Etykieta (sklep)",
+  "detail.mimeType": "Typ MIME",
+  "detail.visibility": "Widoczność",
+  "detail.storage": "Magazyn",
+  "detail.size": "Rozmiar",
+  "detail.bytes": "bajtów",
+  "detail.referencedBy": "Używany przez",
+  "detail.notReferenced": "Brak odwołań.",
+  "detail.softDeleteTitle": "Przenieś zasób do kosza",
+  "detail.softDeleteBlockedTitle": "Najpierw usuń wszystkie odwołania",
+  "detail.softDelete": "Do kosza",
+  "visibility.public": "publiczny",
+  "visibility.private": "prywatny",
+  "folders.title": "Foldery",
+  "folders.root": "Nieposortowane (root)",
+  "folders.namePlaceholder": "Nazwa folderu",
+  "folders.newSubfolder": "Nowy podfolder",
+  "folders.deleteConfirm": "Usunąć ten folder?\n\nOK = przenieś zawartość do folderu nadrzędnego, a potem usuń.\nAnuluj = przerwij.",
+  "folders.removed": "Usunięto folder ({id}).",
+  "nav.assetsLibrary.label": "Biblioteka zasobów"
+}

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@endora-commerce/mod-assets-library",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Storage adapter registry (local / S3 / GCS), asset upload, and reference tracking.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "assets_library"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/assets_library"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3",
+    "@aws-sdk/s3-request-presigner": "^3",
+    "@fastify/multipart": "^10",
+    "@google-cloud/storage": "^7",
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "file-type": "^22",
+    "lucide-react": "^1",
+    "react": "^19",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1042.0",
+    "@aws-sdk/s3-request-presigner": "^3.1042.0",
+    "@fastify/multipart": "^10.0.0",
+    "@google-cloud/storage": "^7.19.0",
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "file-type": "^22.0.1",
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
 }

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-assets-library — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";