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

package/dist/backend/index.js

@@ -0,0 +1,150 @@
+import { resolvePublicApiBaseUrl } from '@endora-commerce/platform/kernel';
+import { assetsLibraryModule } from './plugin.js';
+import { AssetReadService } from './services/asset-read-port.js';
+import { ObjectStorageAdapter } from './services/storage/object-storage-port.js';
+import { AssetFolder } from './entities/asset-folder.entity.js';
+import { Asset } from './entities/asset.entity.js';
+export function registerModule(ctx) {
+    ctx.di.register({
+        assetsLibrary: ctx
+            .asFunction(({ emFactory, auditLogService }) => assetsLibraryModule({
+            emFactory,
+            // D-223 — this module resolves the deployment's public API origin
+            // itself, the idiom `payu`, `tpay` and `inpost` already use for their
+            // callback origins, and every URL it produces is built on it when the
+            // storage adapter's own configured base is blank. It is read here,
+            // inside the factory, so the value is the one this composition boots
+            // with; the platform has already refused a production boot that has
+            // no origin at all (issue #218), so there is no new failure mode.
+            publicApiBaseUrl: resolvePublicApiBaseUrl(),
+            // Resolved per check, not captured. Awilix's strict mode refuses a
+            // singleton holding the transient `requireAdmin` port, and it is
+            // right to: a captured guard keeps admitting requests after `auth`
+            // goes away. This indirection is what the gate being non-optional
+            // buys — there is one guard, and it is always the live one.
+            requireAdmin: (permission) => async (req, reply) => ctx.cradle().requireAdmin(permission)(req, reply),
+            auditLog: auditLogService,
+        }))
+            .singleton(),
+    });
+    /**
+     * The contribution seam, deliberately **ungated** (feature 072, D-39).
+     *
+     * `catalog`, `cms`, `blog` and `megamenu` push their reference scanners in
+     * from `ctx.onBoot`, and boot hooks run regardless of effective state. As a
+     * `providePort` this was a transient gate, so switching `assets_library` off
+     * made all four hooks throw `MODULE_DISABLED` during composition and the
+     * backend stopped starting. A descriptor is inert; `assetsLibraryPort`, which
+     * reads and writes assets, is the port and does fail closed. (That sentence
+     * named `assetsLibraryService` until T118c, which is the container name the
+     * roots contributed rather than a port — it was never gated, and it is gone.)
+     *
+     * Whether an entry is honoured while its contributor is absent is answered at
+     * enumeration — see `services/reference-registry.ts`.
+     *
+     * `AssetReferenceRegistryPort` is published over this name all the same, which
+     * is not a reason to convert it back (issue #192): a published shape and a
+     * gated registration are different questions, and only the first is what F4
+     * packages.
+     */
+    ctx.di.register({
+        assetReferenceRegistry: ctx
+            .asFunction(({ assetsLibrary }) => assetsLibrary.handle.referenceRegistry)
+            .singleton(),
+    });
+    // ---------------------------------------------------------------------------
+    // Feature 075, Phase P — the published surface.
+    //
+    // `assetReadPort` replaces the five `em.findOne(Asset, …)` calls `catalog`
+    // and `orders` make to validate an id an admin supplied before attaching it.
+    //
+    // `assetsLibraryPort` is the narrow face of the library service that
+    // `pim_ergonode` uses during an import — upload, read, patch the alternate
+    // text, soft-delete what an item stopped pointing at. Since T118c it is also
+    // what `cms` resolves to turn an embedded asset id into the detail a
+    // storefront response carries.
+    //
+    // **Phase C has retired the root's entry** (`specs/110-instance-repository/`
+    // T118c). This note used to read *"the existing `assetsLibraryService` name is
+    // still contributed by a composition root; the root's entry stays until Phase
+    // C retires it, and the two resolve the same instance"*. Both roots
+    // contributed that name and, by the time it was drained, **no module resolved
+    // it**: `pim_ergonode` moved to this port at feature 075's cut and the second,
+    // ungated hold on the same service stayed behind. So the drain cost nothing
+    // and bought the one thing the duplicate could not have — there is now exactly
+    // one way in, and it is gated.
+    //
+    // What is still a composition's, and why it is not an omission. This note
+    // read *"five reaches … `resolveUrl` (three of them, two of those also
+    // folding in the host's public API base URL)"* against a tree holding
+    // **eight** reaches, **four** of them `resolveUrl` and **three** of those
+    // absolutizing. The count is not written down again (D-100):
+    // `grep -n 'assetsLibrary\.' backend/src/composition.ts` answers it. What is
+    // true of the reaches that remain is that each needs something this port does
+    // not publish — `resolveUrl`, or the storage adapters' byte-streaming surface
+    // (`invoices`' logo embed, `product_feeds`' artefact writer).
+    //
+    // **What no reach does any more is absolutize** (D-223). The three that did
+    // did it three ways — `absolutizePublicUrl` reading `BACKEND_PUBLIC_URL`
+    // first at two of them, `configuredPublicApiBaseUrl` plus a hand-written join
+    // reading `PUBLIC_API_BASE_URL` first at the third — while the fourth
+    // `resolveUrl` reach did not absolutize at all, so one asset had three
+    // answers depending on which consumer asked, and the two composition roots
+    // disagreed at two of the sites. This module resolves the origin itself now
+    // and every URL it returns is absolute.
+    //
+    // **`objectStoragePort` is the byte-store answer** (T118c), and it is a
+    // sibling of `assetsLibraryPort` rather than four more methods on it: what
+    // `product_feeds` borrows is *which bucket this deployment writes to, with
+    // which credentials*, and it creates no `Asset` row. `invoices`' logo embed
+    // asks the identical question through a composition root and drains onto the
+    // same port. The published shape's own doc block carries its retiring
+    // condition — this is really an object store, and it lives here because the
+    // configuration does.
+    //
+    // **And the URL answer is `assetReadPort.resolvePublicUrls`, in batch.** This
+    // note read *"a consumer that wants a URL for an asset id takes
+    // `AssetsLibraryPort.getAsset`, which already carries one"*, and that is the
+    // right answer for `cms` resolving a handful of embeds on one page. Measured
+    // for a consumer that asks about hundreds at a time, it is not: `getAsset`
+    // builds the full detail, and the detail carries the deletion-protection
+    // `references` list, which is one query per registered reference descriptor —
+    // roughly ten queries per asset against a feed hydration batch of 500
+    // products. The batched read is one query and a string build per row, and it
+    // is the *rule* that moves with it rather than only the loop: only this
+    // module can tell a stable URL from a signed one, so the filter belongs here
+    // and the absence is the return type (composition checklist item 7).
+    // ---------------------------------------------------------------------------
+    ctx.di.providePort('assetReadPort', ctx
+        .asFunction(({ emFactory, assetsLibrary }) => 
+    // The registry is read per call, never captured: it is rebuilt when
+    // the active-backend setting changes, and a URL built by yesterday's
+    // adapter points at a bucket this deployment no longer writes to.
+    new AssetReadService(emFactory, () => assetsLibrary.handle.adapters))
+        .singleton());
+    ctx.di.providePort('assetsLibraryPort', ctx
+        .asFunction(({ assetsLibrary }) => assetsLibrary.handle.service)
+        .singleton());
+    ctx.di.providePort('objectStoragePort', ctx
+        .asFunction(({ assetsLibrary }) => new ObjectStorageAdapter(assetsLibrary.handle.adapters))
+        .singleton());
+    ctx.routes(async (app) => {
+        await ctx.cradle().assetsLibrary.plugin(app);
+    });
+}
+/**
+ * The module's persisted entity classes, on the `./backend` subpath, as one
+ * array and **no named class export** (D-168).
+ *
+ * This is the shape the platform reads when the package is *installed*: the
+ * boot-time loader (`src/packages/package-runtime.ts`, `exported['entities']`)
+ * and the static declaration reader (`scripts/lib/package-declarations.ts`),
+ * which is the third source of `check:module-boundary`'s `table→owner` map and
+ * the package pass of `check-entity-tenant-classification`. A missing array is
+ * answered with `[]` — zero entities registered, no error anywhere.
+ */
+export const entities = [
+    AssetFolder,
+    Asset,
+];
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"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"}

package/dist/backend/jobs/hard-delete-asset.job.d.ts

@@ -0,0 +1,18 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AdapterRegistry } from '../services/storage/adapter-registry.js';
+export interface HardDeleteSweepResult {
+    hardDeleted: number;
+    pendingCleanup: number;
+}
+export declare class HardDeleteAssetWorker {
+    private readonly emFactory;
+    private readonly adapters;
+    constructor(emFactory: () => EntityManager, adapters: AdapterRegistry);
+    sweep(now?: Date): Promise<HardDeleteSweepResult>;
+    /**
+     * Retry pass for rows the worker previously parked in pendingCleanup.
+     * Same logic as `sweep` but selects rows with pending_cleanup = true.
+     */
+    sweepPending(): Promise<HardDeleteSweepResult>;
+}
+//# sourceMappingURL=hard-delete-asset.job.d.ts.map

package/dist/backend/jobs/hard-delete-asset.job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hard-delete-asset.job.d.ts","sourceRoot":"","sources":["../../../src/backend/jobs/hard-delete-asset.job.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAG/E,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,SAAS,EAAE,MAAM,aAAa,EAC9B,QAAQ,EAAE,eAAe;IAGtC,KAAK,CAAC,GAAG,GAAE,IAAiB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoCnE;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,qBAAqB,CAAC;CA8BrD"}

package/dist/backend/jobs/hard-delete-asset.job.js

@@ -0,0 +1,91 @@
+// Hard-delete worker — feature 013 / FR-031 / Phase 9 / T100.
+//
+// Periodic sweep that finalises soft-deleted assets:
+//   1. Find every Asset where deletedAt is set, purgeAfterAt has elapsed,
+//      and pendingCleanup is false.
+//   2. For each, call adapter.delete(locator). Success → DELETE the row.
+//      Failure → set pendingCleanup = true; the row stays soft-deleted and
+//      the worker retries on the next tick.
+//
+// `sweep()` is a plain async method so tests can drive it directly without
+// Redis/BullMQ. Production wiring registers it on the existing repeatable
+// queue (omitted here — repeatable scheduling lives in composition.ts).
+import { Asset } from '../entities/asset.entity.js';
+export class HardDeleteAssetWorker {
+    emFactory;
+    adapters;
+    constructor(emFactory, adapters) {
+        this.emFactory = emFactory;
+        this.adapters = adapters;
+    }
+    async sweep(now = new Date()) {
+        // command-coverage-ignore: retention purge, not an operator write. The
+        // auditable decision was the soft delete that set `deletedAt` and
+        // `purgeAfterAt`; this pass only executes the retention window that write
+        // already committed, with no actor behind it and nothing to undo.
+        const em = this.emFactory();
+        const due = await em.find(Asset, {
+            deletedAt: { $ne: null },
+            purgeAfterAt: { $lte: now },
+            pendingCleanup: false,
+        });
+        let hardDeleted = 0;
+        let newlyPending = 0;
+        for (const a of due) {
+            const adapter = await this.adapters.getForBackend(a.storageBackend);
+            // Legacy resolver has no delete — skip and just hard-delete the row.
+            if (!('delete' in adapter) || typeof adapter.delete !== 'function') {
+                em.remove(a);
+                hardDeleted += 1;
+                continue;
+            }
+            try {
+                await adapter.delete({ locator: a.storageLocator || a.storageUrl });
+                em.remove(a);
+                hardDeleted += 1;
+            }
+            catch {
+                a.pendingCleanup = true;
+                newlyPending += 1;
+            }
+        }
+        if (due.length > 0)
+            await em.flush();
+        return { hardDeleted, pendingCleanup: newlyPending };
+    }
+    /**
+     * Retry pass for rows the worker previously parked in pendingCleanup.
+     * Same logic as `sweep` but selects rows with pending_cleanup = true.
+     */
+    async sweepPending() {
+        // command-coverage-ignore: the retry half of `sweep()` — same already-audited
+        // retention decision, re-attempted for rows whose storage delete failed.
+        const em = this.emFactory();
+        const due = await em.find(Asset, {
+            deletedAt: { $ne: null },
+            pendingCleanup: true,
+        });
+        let hardDeleted = 0;
+        let stillPending = 0;
+        for (const a of due) {
+            const adapter = await this.adapters.getForBackend(a.storageBackend);
+            if (!('delete' in adapter) || typeof adapter.delete !== 'function') {
+                em.remove(a);
+                hardDeleted += 1;
+                continue;
+            }
+            try {
+                await adapter.delete({ locator: a.storageLocator || a.storageUrl });
+                em.remove(a);
+                hardDeleted += 1;
+            }
+            catch {
+                stillPending += 1;
+            }
+        }
+        if (due.length > 0)
+            await em.flush();
+        return { hardDeleted, pendingCleanup: stillPending };
+    }
+}
+//# sourceMappingURL=hard-delete-asset.job.js.map

package/dist/backend/jobs/hard-delete-asset.job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hard-delete-asset.job.js","sourceRoot":"","sources":["../../../src/backend/jobs/hard-delete-asset.job.ts"],"names":[],"mappings":"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"}

package/dist/backend/plugin.d.ts

@@ -0,0 +1,47 @@
+import type { FastifyInstance } from 'fastify';
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { AdapterRegistry } from './services/storage/adapter-registry.js';
+import { AssetsLibraryService } from './services/assets-library.service.js';
+import { FoldersService } from './services/folders.service.js';
+import { AssetReferenceRegistry } from './services/reference-registry.js';
+import { HmacSigner } from './services/hmac.js';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import type { RequireAdminFactory } from '@endora-commerce/platform/kernel';
+export interface AssetsLibraryModuleOptions {
+    emFactory: () => EntityManager;
+    /** HMAC signer for local-FS private URLs. Uses ASSETS_LIBRARY_HMAC_KEY by default. */
+    signer?: HmacSigner;
+    /**
+     * Permission gate factory. **Required** since feature 072 (T092): it used to
+     * default to a permissive no-op, so a caller that forgot it got an
+     * unguarded asset admin surface — silently, because the safe path is the one
+     * every test exercises. The container supplies it now; there is no omission
+     * left to be silent about.
+     */
+    requireAdmin: RequireAdminFactory;
+    /**
+     * This deployment's resolved public API origin, and the base every URL this
+     * module produces falls back to (D-223).
+     *
+     * **Required**, for the reason the gate above is: an omitted origin is not a
+     * failure, it is a host-relative URL in an e-mail, a push payload and a
+     * partner's feed — silent, and invisible to every test that reads the URL
+     * from the same host that served it. `registerModule` resolves it with the
+     * platform's `resolvePublicApiBaseUrl()`, which is the idiom the payment
+     * modules already use for their callback origins.
+     */
+    publicApiBaseUrl: string;
+    /** Feature 054 — audits asset/folder writes co-transactionally when provided. */
+    auditLog?: AuditPort;
+}
+export interface AssetsLibraryModuleHandle {
+    service: AssetsLibraryService;
+    folders: FoldersService;
+    referenceRegistry: AssetReferenceRegistry;
+    adapters: AdapterRegistry;
+}
+export declare function assetsLibraryModule(options: AssetsLibraryModuleOptions): {
+    plugin: (app: FastifyInstance) => Promise<void>;
+    handle: AssetsLibraryModuleHandle;
+};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/backend/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/backend/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAMlE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,sFAAsF;IACtF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,EAAE,mBAAmB,CAAC;IAClC;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB,iBAAiB,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAyBD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG;IACxE,MAAM,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,EAAE,yBAAyB,CAAC;CACnC,CAqEA"}

package/dist/backend/plugin.js

@@ -0,0 +1,96 @@
+// Assets Library — Fastify plugin / composition root for the module.
+import fastifyMultipart from '@fastify/multipart';
+import { AdapterRegistry } from './services/storage/adapter-registry.js';
+import { AssetsLibraryService } from './services/assets-library.service.js';
+import { FoldersService } from './services/folders.service.js';
+import { AssetReferenceRegistry } from './services/reference-registry.js';
+import { HmacSigner } from './services/hmac.js';
+import { createSettingsView } from './services/storage/settings-view.js';
+import { Setting } from '@endora-commerce/platform/kernel';
+import { SettingValue } from '@endora-commerce/platform/kernel';
+import { registerAssetsLibraryAdminRoutes } from './routes.admin.js';
+import { registerAssetsLibraryPublicRoutes } from './routes.public.js';
+async function loadUploadPolicy(emFactory) {
+    const em = emFactory();
+    const allowed = await em.findOne(Setting, { code: 'assets.allowed_file_types' });
+    const allowedOverride = allowed
+        ? await em.findOne(SettingValue, { setting: allowed })
+        : null;
+    const allowedRaw = allowedOverride
+        ? allowedOverride.value
+        : allowed?.defaultValue ?? ['*'];
+    const allowedTypes = Array.isArray(allowedRaw) ? allowedRaw.map(String) : ['*'];
+    const max = await em.findOne(Setting, { code: 'assets.max_file_size_mb' });
+    const maxOverride = max ? await em.findOne(SettingValue, { setting: max }) : null;
+    const maxRaw = maxOverride ? maxOverride.value : max?.defaultValue ?? 0;
+    const maxFileSizeMb = typeof maxRaw === 'number' ? maxRaw : Number(maxRaw) || 0;
+    return { allowedTypes, maxFileSizeMb };
+}
+export function assetsLibraryModule(options) {
+    let cachedSigner = options.signer;
+    const adapters = new AdapterRegistry({
+        settings: createSettingsView(options.emFactory),
+        publicApiBaseUrl: options.publicApiBaseUrl,
+        signer: () => {
+            if (!cachedSigner)
+                cachedSigner = HmacSigner.fromEnv();
+            return cachedSigner;
+        },
+    });
+    const referenceRegistry = new AssetReferenceRegistry();
+    const service = new AssetsLibraryService({
+        emFactory: options.emFactory,
+        adapters,
+        referenceRegistry,
+        loadUploadPolicy: () => loadUploadPolicy(options.emFactory),
+        ...(options.auditLog ? { auditLog: options.auditLog } : {}),
+    });
+    const folders = new FoldersService(options.emFactory, referenceRegistry, options.auditLog);
+    const requireAdmin = options.requireAdmin;
+    const plugin = async (app) => {
+        // Resolve the upload policy ONCE at registration so the multipart
+        // parser's hard cap matches the operator-configured maximum. Without
+        // an explicit `fileSize`, @fastify/multipart silently falls back to
+        // its 1 MiB default and tears down the file stream on anything larger
+        // — which surfaces as a 500 from the awaited adapter pipeline rather
+        // than a clean 413 (the symptom that motivated this code).
+        //
+        // The pipeline's per-request size check still runs against the LIVE
+        // setting on every upload, so tightening the cap takes effect without
+        // a restart. Loosening it (or switching from a finite cap to "no cap")
+        // requires a backend restart for the multipart parser to pick up the
+        // new `fileSize` value.
+        const initialPolicy = await loadUploadPolicy(options.emFactory);
+        const FALLBACK_HARD_CEILING_BYTES = 5 * 1024 * 1024 * 1024; // 5 GiB
+        const multipartFileSize = initialPolicy.maxFileSizeMb > 0
+            ? initialPolicy.maxFileSizeMb * 1024 * 1024
+            : FALLBACK_HARD_CEILING_BYTES;
+        // Multipart is registered in a child encapsulation context so other modules'
+        // routes are unaffected by its options.
+        await app.register(async (childApp) => {
+            await childApp.register(fastifyMultipart, {
+                // Keep memory bounded; upload-pipeline streams directly to the adapter.
+                limits: { files: 1, fields: 10, fileSize: multipartFileSize },
+            });
+            await registerAssetsLibraryAdminRoutes(childApp, {
+                service,
+                folders,
+                adapters,
+                emFactory: options.emFactory,
+                requireAdmin,
+            });
+        });
+        await registerAssetsLibraryPublicRoutes(app, {
+            service,
+            adapters,
+            emFactory: options.emFactory,
+            signer: () => {
+                if (!cachedSigner)
+                    cachedSigner = HmacSigner.fromEnv();
+                return cachedSigner;
+            },
+        });
+    };
+    return { plugin, handle: { service, folders, referenceRegistry, adapters } };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/backend/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/backend/plugin.ts"],"names":[],"mappings":"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"}

package/dist/backend/routes.admin.d.ts

@@ -0,0 +1,15 @@
+import type { FastifyInstance } from 'fastify';
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AssetsLibraryService } from './services/assets-library.service.js';
+import type { FoldersService } from './services/folders.service.js';
+import type { AdapterRegistry } from './services/storage/adapter-registry.js';
+import type { RequireAdminFactory } from '@endora-commerce/platform/kernel';
+export interface AdminRoutesDeps {
+    service: AssetsLibraryService;
+    folders: FoldersService;
+    adapters: AdapterRegistry;
+    emFactory: () => EntityManager;
+    requireAdmin: RequireAdminFactory;
+}
+export declare function registerAssetsLibraryAdminRoutes(app: FastifyInstance, deps: AdminRoutesDeps): Promise<void>;
+//# sourceMappingURL=routes.admin.d.ts.map

package/dist/backend/routes.admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.admin.d.ts","sourceRoot":"","sources":["../../src/backend/routes.admin.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAc3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED,wBAAsB,gCAAgC,CACpD,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,IAAI,CAAC,CAmQf"}

package/dist/backend/routes.admin.js

@@ -0,0 +1,189 @@
+// Admin HTTP surface for the Assets Library — feature 013 / US1.
+// Mounts under /api/v1/admin/assets/*.
+//
+// Routes implemented in this phase (US1):
+//   POST   /api/v1/admin/assets             — multipart upload
+//   GET    /api/v1/admin/assets             — list (folder filter + pagination)
+//   GET    /api/v1/admin/assets/:id         — detail with references
+//   GET    /api/v1/admin/assets/:id/url     — re-resolve URL on demand
+//   PATCH  /api/v1/admin/assets/:id         — edit metadata + visibility flip
+//
+// Folder CRUD, soft-delete, restore, bulk move, and storage self-check
+// land in subsequent user stories.
+import { ERROR_CODES, patchAssetRequestSchema, listAssetsQuerySchema, createFolderRequestSchema, patchFolderRequestSchema, deleteFolderRequestSchema, moveAssetRequestSchema, moveManyAssetsRequestSchema, } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { Asset } from './entities/asset.entity.js';
+export async function registerAssetsLibraryAdminRoutes(app, deps) {
+    const { service, folders, adapters, emFactory, requireAdmin } = deps;
+    // — POST /assets (multipart upload) -----------------------------------------
+    app.post('/api/v1/admin/assets', { preHandler: requireAdmin('assets.write') }, async (req, reply) => {
+        // Confirm we're handling a multipart request.
+        if (!req.isMultipart()) {
+            throw new HttpError(400, ERROR_CODES.ASSET_UPLOAD_NO_FILE, 'Upload requires multipart/form-data with a `file` part.');
+        }
+        // Collect non-file fields once; @fastify/multipart streams parts.
+        let folderId = null;
+        let label = null;
+        let visibility = 'public';
+        let asset = null;
+        for await (const part of req.parts()) {
+            if (part.type === 'file') {
+                if (asset) {
+                    throw new HttpError(400, ERROR_CODES.ASSET_UPLOAD_NO_FILE, 'Only one file per request is allowed.');
+                }
+                asset = await service.upload({
+                    filename: part.filename ?? 'unknown',
+                    declaredMime: part.mimetype ?? 'application/octet-stream',
+                    stream: part.file,
+                    // @fastify/multipart does not provide a guaranteed size.
+                    declaredSize: 0,
+                    folderId,
+                    label,
+                    visibility,
+                });
+            }
+            else if (part.fieldname === 'folderId') {
+                folderId = part.value || null;
+            }
+            else if (part.fieldname === 'label') {
+                label = part.value || null;
+            }
+            else if (part.fieldname === 'visibility') {
+                const v = part.value;
+                if (v !== 'public' && v !== 'private') {
+                    throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, `visibility must be public|private; got "${v}".`);
+                }
+                visibility = v;
+            }
+        }
+        if (!asset) {
+            throw new HttpError(400, ERROR_CODES.ASSET_UPLOAD_NO_FILE, 'Multipart body did not include a `file` part.');
+        }
+        reply.status(201);
+        return { data: asset };
+    });
+    // — GET /assets (paginated list) -------------------------------------------
+    app.get('/api/v1/admin/assets', {
+        preHandler: requireAdmin('assets.read'),
+    }, async (req) => {
+        const parsed = listAssetsQuerySchema.parse(req.query);
+        const out = await service.listAssets({
+            folderId: parsed.folderId ?? null,
+            ...(parsed.q !== undefined ? { q: parsed.q } : {}),
+            ...(parsed.mime !== undefined ? { mime: parsed.mime } : {}),
+            ...(parsed.visibility !== undefined ? { visibility: parsed.visibility } : {}),
+            includeDeleted: parsed.includeDeleted,
+            ...(parsed.cursor !== undefined ? { cursor: parsed.cursor } : {}),
+            limit: parsed.limit,
+        });
+        return out;
+    });
+    // — GET /assets/:id --------------------------------------------------------
+    app.get('/api/v1/admin/assets/:id', { preHandler: requireAdmin('assets.read') }, async (req) => {
+        const detail = await service.getAsset(req.params.id);
+        return { data: detail };
+    });
+    // — GET /assets/:id/url ----------------------------------------------------
+    app.get('/api/v1/admin/assets/:id/url', { preHandler: requireAdmin('assets.read') }, async (req) => {
+        const resolved = await service.resolveUrl(req.params.id);
+        return {
+            data: {
+                url: resolved.url,
+                expiresAt: resolved.expiresAt ? resolved.expiresAt.toISOString() : null,
+            },
+        };
+    });
+    // — DELETE /assets/:id (soft-delete + reference protection) ---------------
+    app.delete('/api/v1/admin/assets/:id', { preHandler: requireAdmin('assets.write') }, async (req) => {
+        const out = await service.softDelete(req.params.id);
+        return {
+            data: {
+                deletedAt: out.deletedAt.toISOString(),
+                purgeAfterAt: out.purgeAfterAt.toISOString(),
+            },
+        };
+    });
+    // — POST /assets/:id/restore ----------------------------------------------
+    app.post('/api/v1/admin/assets/:id/restore', { preHandler: requireAdmin('assets.write') }, async (req) => {
+        const detail = await service.restore(req.params.id);
+        return { data: detail };
+    });
+    // — POST /assets/:id/move --------------------------------------------------
+    app.post('/api/v1/admin/assets/:id/move', { preHandler: requireAdmin('assets.write') }, async (req) => {
+        const body = moveAssetRequestSchema.parse(req.body);
+        const detail = await service.move(req.params.id, body.folderId ?? null);
+        return { data: detail };
+    });
+    // — POST /assets/move-many -------------------------------------------------
+    app.post('/api/v1/admin/assets/move-many', { preHandler: requireAdmin('assets.write') }, async (req) => {
+        const body = moveManyAssetsRequestSchema.parse(req.body);
+        const out = await service.moveMany(body.assetIds, body.folderId ?? null);
+        return { data: out };
+    });
+    // — Storage administration -------------------------------------------------
+    app.post('/api/v1/admin/assets/storage/self-check', { preHandler: requireAdmin('assets.write') }, async () => {
+        const adapter = await adapters.getActive();
+        const result = await adapter.selfCheck();
+        return {
+            data: { adapter: adapter.code, ...result },
+        };
+    });
+    app.get('/api/v1/admin/assets/storage/state', { preHandler: requireAdmin('assets.read') }, async () => {
+        const adapter = await adapters.getActive().catch((err) => {
+            return {
+                code: 'local',
+                // Surface the misconfig as a not-ok self-check rather than 500.
+                async selfCheck() {
+                    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+                },
+            };
+        });
+        const result = await adapter.selfCheck();
+        const em = emFactory();
+        const pendingCleanupCount = await em.count(Asset, { pendingCleanup: true });
+        const softDeletedCount = await em.count(Asset, { deletedAt: { $ne: null } });
+        return {
+            data: {
+                activeAdapter: adapter.code,
+                selfCheck: result,
+                pendingCleanupCount,
+                softDeletedCount,
+            },
+        };
+    });
+    // — Folders ----------------------------------------------------------------
+    app.get('/api/v1/admin/assets/folders', { preHandler: requireAdmin('assets.read') }, async () => ({ data: await folders.listFolderTree() }));
+    app.post('/api/v1/admin/assets/folders', { preHandler: requireAdmin('assets.write') }, async (req, reply) => {
+        const body = createFolderRequestSchema.parse(req.body);
+        const f = await folders.createFolder(body);
+        reply.status(201);
+        return { data: f };
+    });
+    app.patch('/api/v1/admin/assets/folders/:folderId', { preHandler: requireAdmin('assets.write') }, async (req) => {
+        const body = patchFolderRequestSchema.parse(req.body);
+        const f = await folders.patchFolder(req.params.folderId, {
+            ...(body.name !== undefined ? { name: body.name } : {}),
+            ...(body.parentId !== undefined ? { parentId: body.parentId } : {}),
+            ...(body.position !== undefined ? { position: body.position } : {}),
+        });
+        return { data: f };
+    });
+    app.delete('/api/v1/admin/assets/folders/:folderId', { preHandler: requireAdmin('assets.write') }, async (req) => {
+        const body = deleteFolderRequestSchema.parse(req.body ?? {});
+        const out = await folders.deleteFolder(req.params.folderId, body.ifNonEmpty);
+        return { data: out };
+    });
+    // — PATCH /assets/:id ------------------------------------------------------
+    app.patch('/api/v1/admin/assets/:id', { preHandler: requireAdmin('assets.write') }, async (req) => {
+        const patch = patchAssetRequestSchema.parse(req.body);
+        const detail = await service.patchAsset(req.params.id, {
+            ...(patch.filename !== undefined ? { filename: patch.filename } : {}),
+            ...(patch.label !== undefined ? { label: patch.label } : {}),
+            ...(patch.mimeType !== undefined ? { mimeType: patch.mimeType } : {}),
+            ...(patch.visibility !== undefined ? { visibility: patch.visibility } : {}),
+            ...(patch.folderId !== undefined ? { folderId: patch.folderId } : {}),
+        });
+        return { data: detail };
+    });
+}
+//# sourceMappingURL=routes.admin.js.map