@spinekit/media 0.1.1

package/dist/config/media.defaults.d.mts

@@ -0,0 +1,131 @@
+//#region src/config/media.defaults.d.ts
+/**
+ * Commerce media DEFAULTS — folders, size variants, aspect ratios, processing.
+ *
+ * These are opinionated defaults for a commerce catalog, not universal truths, so every
+ * one is overridable. A fork that sells services instead of goods drops `products`; a
+ * fork that needs a `hero` ratio adds one. Nobody should have to edit package source to
+ * change a folder list.
+ *
+ * They live here rather than in a host because the SHAPE is shared: any commerce
+ * deployment wants product/category/banner/brand imagery with bounded variants. Only the
+ * values vary, and values are what `mergeMediaDefaults` takes.
+ */
+/**
+ * `branding` holds document branding assets (invoice/report logos) — deliberately separate
+ * from `brands` (product manufacturer imagery), so a bill-logo picker can scope to it
+ * without wading through product marketing media.
+ */
+declare const BASE_FOLDERS: readonly ['general', 'products', 'categories', 'blog', 'users', 'banners', 'brands', 'branding'];
+/**
+ * Variants auto-generated per uploaded image. `width`/`height` are MAX BOUNDS — the aspect
+ * ratio is decided by the presets below, not here.
+ */
+declare const SIZE_VARIANTS: readonly [{
+  readonly name: 'thumbnail';
+  readonly width: 200;
+  readonly height: 200;
+  readonly quality: 80;
+  readonly format: 'avif';
+}, {
+  readonly name: 'medium';
+  readonly width: 800;
+  readonly height: 800;
+  readonly quality: 80;
+  readonly format: 'avif';
+}];
+/**
+ * Aspect-ratio presets by content type.
+ *
+ * `preserveRatio: true` scales to fit within the bounds and never crops or distorts.
+ * `aspectRatio` + `fit: 'cover'` crops to an exact ratio — used only for avatars, where a
+ * square is expected and a letterboxed face looks broken.
+ */
+declare const ASPECT_RATIO_PRESETS: {
+  readonly default: {
+    readonly preserveRatio: true;
+  };
+  readonly product: {
+    readonly preserveRatio: true;
+  };
+  readonly category: {
+    readonly preserveRatio: true;
+  };
+  readonly banner: {
+    readonly preserveRatio: true;
+  };
+  readonly brand: {
+    readonly preserveRatio: true;
+  };
+  readonly avatar: {
+    readonly aspectRatio: 1;
+    readonly fit: 'cover';
+  };
+};
+/** Folder → content-type mapping for auto-detection when no `contentType` is supplied. */
+declare const FOLDER_CONTENT_TYPE_MAP: {
+  readonly product: readonly ['products', 'product'];
+  readonly category: readonly ['categories', 'category'];
+  readonly banner: readonly ['banners', 'banner'];
+  readonly avatar: readonly ['users', 'avatars'];
+  readonly brand: readonly ['brands', 'brand'];
+};
+declare const IMAGE_SETTINGS: {
+  readonly defaultMaxWidth: 3840;
+  readonly quality: {
+    readonly jpeg: 85;
+    readonly webp: 85;
+    readonly avif: 80;
+    readonly png: 100;
+  };
+  readonly format: 'avif';
+  readonly generateAlt: {
+    readonly enabled: true;
+    readonly strategy: 'filename';
+    readonly fallback: 'Image';
+  };
+  /**
+   * What may be STORED. Permissive by default — the host owns this list.
+   *
+   * SVG is included. It is worth knowing what that means so the choice is an
+   * informed one rather than an accident: an SVG is executable markup, so one
+   * served from an origin that shares cookies with the app can run script with
+   * the viewer's session. The presigned path cannot rule it out either — the
+   * server never sees the bytes, and the MIME it cross-checks against storage
+   * is the one the same client supplied during its signed PUT.
+   *
+   * That is a deployment decision, not a package one, and it has ordinary
+   * answers: serve media from a cookie-free origin, send
+   * `Content-Disposition: attachment`, or sanitise on upload. A deployment that
+   * wants a stricter set overrides `imageSettings.allowedMimeTypes` — brand
+   * marks and icon sets are commonly SVG, so removing it here would break real
+   * uploads to enforce a posture the host may already handle elsewhere.
+   *
+   * SEPARATE and NOT a policy: whether a format can be re-encoded without
+   * destroying it. SVG and animated GIF cannot (rasterising loses the vector;
+   * a one-frame re-encode loses the animation), so both are excluded from the
+   * client TRANSFORM path in `@classytic/media-transform/policy`. That is a
+   * fact about the format, which the package owns — being storable and being
+   * transformable are different questions.
+   */
+  readonly allowedMimeTypes: readonly ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/gif', 'image/svg+xml', 'image/avif'];
+  readonly maxSize: number;
+};
+interface MediaDefaults {
+  baseFolders: readonly string[];
+  sizeVariants: readonly Record<string, unknown>[];
+  aspectRatioPresets: Record<string, unknown>;
+  folderContentTypeMap: Record<string, readonly string[]>;
+  imageSettings: Record<string, unknown>;
+}
+declare const MEDIA_DEFAULTS: MediaDefaults;
+/**
+ * Merge a deployment's overrides over the defaults.
+ *
+ * Shallow PER KEY on purpose: a fork that supplies `baseFolders` means *these folders*,
+ * not "these in addition to mine". Deep-merging a list would make removing a default
+ * folder impossible, which is the main reason a fork overrides it at all.
+ */
+declare function mergeMediaDefaults(overrides?: Partial<MediaDefaults>): MediaDefaults;
+//#endregion
+export { ASPECT_RATIO_PRESETS, BASE_FOLDERS, FOLDER_CONTENT_TYPE_MAP, IMAGE_SETTINGS, MEDIA_DEFAULTS, MediaDefaults, SIZE_VARIANTS, mergeMediaDefaults };

package/dist/config/media.defaults.mjs

@@ -0,0 +1,145 @@
+//#region src/config/media.defaults.ts
+/**
+* Commerce media DEFAULTS — folders, size variants, aspect ratios, processing.
+*
+* These are opinionated defaults for a commerce catalog, not universal truths, so every
+* one is overridable. A fork that sells services instead of goods drops `products`; a
+* fork that needs a `hero` ratio adds one. Nobody should have to edit package source to
+* change a folder list.
+*
+* They live here rather than in a host because the SHAPE is shared: any commerce
+* deployment wants product/category/banner/brand imagery with bounded variants. Only the
+* values vary, and values are what `mergeMediaDefaults` takes.
+*/
+/**
+* `branding` holds document branding assets (invoice/report logos) — deliberately separate
+* from `brands` (product manufacturer imagery), so a bill-logo picker can scope to it
+* without wading through product marketing media.
+*/
+const BASE_FOLDERS = [
+	"general",
+	"products",
+	"categories",
+	"blog",
+	"users",
+	"banners",
+	"brands",
+	"branding"
+];
+/**
+* Variants auto-generated per uploaded image. `width`/`height` are MAX BOUNDS — the aspect
+* ratio is decided by the presets below, not here.
+*/
+const SIZE_VARIANTS = [{
+	name: "thumbnail",
+	width: 200,
+	height: 200,
+	quality: 80,
+	format: "avif"
+}, {
+	name: "medium",
+	width: 800,
+	height: 800,
+	quality: 80,
+	format: "avif"
+}];
+/**
+* Aspect-ratio presets by content type.
+*
+* `preserveRatio: true` scales to fit within the bounds and never crops or distorts.
+* `aspectRatio` + `fit: 'cover'` crops to an exact ratio — used only for avatars, where a
+* square is expected and a letterboxed face looks broken.
+*/
+const ASPECT_RATIO_PRESETS = {
+	default: { preserveRatio: true },
+	product: { preserveRatio: true },
+	category: { preserveRatio: true },
+	banner: { preserveRatio: true },
+	brand: { preserveRatio: true },
+	avatar: {
+		aspectRatio: 1,
+		fit: "cover"
+	}
+};
+/** Folder → content-type mapping for auto-detection when no `contentType` is supplied. */
+const FOLDER_CONTENT_TYPE_MAP = {
+	product: ["products", "product"],
+	category: ["categories", "category"],
+	banner: ["banners", "banner"],
+	avatar: ["users", "avatars"],
+	brand: ["brands", "brand"]
+};
+const IMAGE_SETTINGS = {
+	defaultMaxWidth: 3840,
+	quality: {
+		jpeg: 85,
+		webp: 85,
+		avif: 80,
+		png: 100
+	},
+	format: "avif",
+	generateAlt: {
+		enabled: true,
+		strategy: "filename",
+		fallback: "Image"
+	},
+	/**
+	* What may be STORED. Permissive by default — the host owns this list.
+	*
+	* SVG is included. It is worth knowing what that means so the choice is an
+	* informed one rather than an accident: an SVG is executable markup, so one
+	* served from an origin that shares cookies with the app can run script with
+	* the viewer's session. The presigned path cannot rule it out either — the
+	* server never sees the bytes, and the MIME it cross-checks against storage
+	* is the one the same client supplied during its signed PUT.
+	*
+	* That is a deployment decision, not a package one, and it has ordinary
+	* answers: serve media from a cookie-free origin, send
+	* `Content-Disposition: attachment`, or sanitise on upload. A deployment that
+	* wants a stricter set overrides `imageSettings.allowedMimeTypes` — brand
+	* marks and icon sets are commonly SVG, so removing it here would break real
+	* uploads to enforce a posture the host may already handle elsewhere.
+	*
+	* SEPARATE and NOT a policy: whether a format can be re-encoded without
+	* destroying it. SVG and animated GIF cannot (rasterising loses the vector;
+	* a one-frame re-encode loses the animation), so both are excluded from the
+	* client TRANSFORM path in `@classytic/media-transform/policy`. That is a
+	* fact about the format, which the package owns — being storable and being
+	* transformable are different questions.
+	*/
+	allowedMimeTypes: [
+		"image/jpeg",
+		"image/jpg",
+		"image/png",
+		"image/webp",
+		"image/gif",
+		"image/svg+xml",
+		"image/avif"
+	],
+	maxSize: 52428800
+};
+const MEDIA_DEFAULTS = {
+	baseFolders: BASE_FOLDERS,
+	sizeVariants: SIZE_VARIANTS,
+	aspectRatioPresets: ASPECT_RATIO_PRESETS,
+	folderContentTypeMap: FOLDER_CONTENT_TYPE_MAP,
+	imageSettings: IMAGE_SETTINGS
+};
+/**
+* Merge a deployment's overrides over the defaults.
+*
+* Shallow PER KEY on purpose: a fork that supplies `baseFolders` means *these folders*,
+* not "these in addition to mine". Deep-merging a list would make removing a default
+* folder impossible, which is the main reason a fork overrides it at all.
+*/
+function mergeMediaDefaults(overrides = {}) {
+	return {
+		baseFolders: overrides.baseFolders ?? MEDIA_DEFAULTS.baseFolders,
+		sizeVariants: overrides.sizeVariants ?? MEDIA_DEFAULTS.sizeVariants,
+		aspectRatioPresets: overrides.aspectRatioPresets ?? MEDIA_DEFAULTS.aspectRatioPresets,
+		folderContentTypeMap: overrides.folderContentTypeMap ?? MEDIA_DEFAULTS.folderContentTypeMap,
+		imageSettings: overrides.imageSettings ?? MEDIA_DEFAULTS.imageSettings
+	};
+}
+//#endregion
+export { ASPECT_RATIO_PRESETS, BASE_FOLDERS, FOLDER_CONTENT_TYPE_MAP, IMAGE_SETTINGS, MEDIA_DEFAULTS, SIZE_VARIANTS, mergeMediaDefaults };

package/dist/index.d.mts

@@ -0,0 +1,243 @@
+import { ResourceSeams } from "@classytic/arc";
+import { EngineSlot } from "@spinekit/kit/engine-slot";
+import { MediaTransformPolicy } from "@classytic/media-transform/policy";
+import { CompleteMultipartInput, ConfirmUploadInput, IMediaDocument, MediaContext, MediaEngine, MultipartUploadSession, MultipartUploadSession as MultipartUploadSession$1, PresignedUploadResult, PresignedUploadResult as PresignedUploadResult$1 } from "@classytic/media-kit";
+import { ArcModule } from "@classytic/arc/factory";
+import { ScheduleDefinition } from "@classytic/arc/plugins";
+import { CleanupStep } from "@classytic/repo-core/cleanup";
+//#region src/cleanup.d.ts
+interface MediaCleanupStepsOptions {
+  /**
+   * Cutoff for the soft-delete purge. Omitted → the kernel's own default
+   * (`softDelete.ttlDays`, 30 days). Passing a NARROWER window is the
+   * supported way to bound a single run's blast radius.
+   */
+  deletedOlderThan?: Date;
+  /** Cutoff for stale `pending`/`deleting` rows. Omitted → kernel default. */
+  stalePendingOlderThan?: Date;
+  /** Expiry horizon. Omitted → "now" (everything already expired). */
+  expiredBefore?: Date;
+  /** Tenant/actor context handed to the kernel verbs. */
+  ctx?: MediaContext;
+}
+/**
+ * The three media purge steps, in the order a full cleanup should run them:
+ * stale uploads first (cheapest, unblocks nothing), then expired assets, then
+ * the soft-delete backlog.
+ */
+declare function mediaCleanupSteps(engine: Pick<MediaEngine, 'repositories'>, options?: MediaCleanupStepsOptions): CleanupStep[];
+//#endregion
+//#region src/index.d.ts
+/** An arc permission gate — sync/async, boolean or PermissionResult. */
+type PermissionGate = import('@classytic/arc/permissions').PermissionCheck;
+interface MediaPermissions {
+  /** List/read media + mint signed read URLs. */
+  view: PermissionGate;
+  /** Start/complete uploads (the two-phase flow). */
+  upload: PermissionGate;
+  /** Delete (soft per engine config) and other mutations. */
+  manage: PermissionGate;
+}
+declare function createMediaRolePermissions(input: {
+  view: readonly string[];
+  upload: readonly string[];
+  manage: readonly string[];
+}): MediaPermissions;
+declare function createMediaEngineSlot<TEngine extends MediaEngineLike = MediaEngineLike>(): EngineSlot<TEngine>;
+/**
+ * The slice of a `@classytic/media-kit` engine this module needs — typed
+ * with the kernel's OWN bags (the kernel is already a peer, so this adds no
+ * new coupling; the 2.21 kernel-port standard across the spine).
+ */
+interface MediaEngineLike {
+  /**
+   * The ONE teardown name (STANDARDIZATION-PLAN §6.4). Declared so `closeOwned`
+   * cannot be written against an engine with no way to be closed.
+   */
+  close(): void | Promise<void>;
+  config: Pick<MediaEngine['config'], 'tenant'>;
+  models: MediaEngine['models'];
+  repositories: MediaEngine['repositories'];
+}
+/** Wire body for `POST /media/start-write`. */
+interface StartWriteBody {
+  filename: string;
+  contentType: string;
+  /** Total bytes — drives the multipart threshold decision. */
+  size?: number;
+  folder?: string;
+  /**
+   * Client-computed content hash (e.g. media-transform's `sha256Hex`).
+   * A tenant-scoped hash hit short-circuits: no upload happens at all.
+   */
+  sha256?: string;
+  /** Force a multipart/resumable session regardless of size. */
+  multipart?: boolean;
+  /** Sign all parts up-front (S3 multipart). */
+  partCount?: number;
+  /** Presigned URL validity in seconds. */
+  expiresIn?: number;
+  /**
+   * Sizes the client produced from the SAME decode and intends to upload.
+   *
+   * Requested here rather than in a second round trip because the client
+   * already knows them: the transform policy told it which to make, and it made
+   * them before asking for anywhere to put them.
+   */
+  derivatives?: Array<{
+    name: string;
+    contentType: string;
+    size?: number;
+  }>;
+}
+/** Discriminated result of `POST /media/start-write`. */
+type StartWriteResult = {
+  kind: 'dedup';
+  media: IMediaDocument;
+} | {
+  kind: 'presigned';
+  upload: PresignedUploadResult$1;
+  /**
+   * One presigned PUT per requested derivative, keyed by variant name.
+   * Absent when none were requested. Keys are DERIVED server-side from the
+   * primary's — a client never names its own storage location.
+   */
+  derivativeUploads?: Array<{
+    name: string;
+    upload: PresignedUploadResult$1;
+  }>;
+} | {
+  kind: 'multipart' | 'resumable';
+  session: MultipartUploadSession$1;
+};
+/**
+ * Explicit engine ownership (STANDARDIZATION-PLAN §7.3) — identical vocabulary
+ * to `@spinekit/catalog`, deliberately: two spine modules inventing two ways to
+ * say "who closes this" is how a fleet ends up with two lifecycle stories.
+ */
+type MediaEngineSource<TEngine> = {
+  readonly kind: 'blueprint';
+  readonly blueprint: {
+    bind(connection: unknown, runtime: never): TEngine | Promise<TEngine>;
+  };
+  readonly connection: unknown;
+  /** Runtime collaborators, or a thunk — building a storage driver is live work. */
+  readonly runtime: unknown | (() => unknown | Promise<unknown>);
+} | {
+  readonly kind: 'external';
+  readonly engine: TEngine;
+};
+interface MediaResourceDeps<TEngine extends MediaEngineLike = MediaEngineLike> {
+  /**
+   * The bound engine.
+   *
+   * Required when building a resource directly; the MODULE supplies it from
+   * its slot, so a module caller passes `source` instead.
+   */
+  engine: TEngine;
+  permissions: MediaPermissions;
+  /**
+   * The client-transform policy served at `GET {prefix}/transform-policy`.
+   *
+   * Defaults to `buildTransformPolicy()`, which DERIVES it from this package's
+   * media shape (size variants, avatar folders, image settings) so the rule the
+   * client follows and the variants the server declares cannot drift apart.
+   * Pass one to state deployment specifics — most importantly
+   * `untouchedFolders`, since only the deployment knows which of its folders
+   * hold documents rather than photographs.
+   */
+  transformPolicy?: MediaTransformPolicy;
+  /** Route prefix. Default `/media`. */
+  prefix?: string;
+  /**
+   * `start-write` returns a multipart/resumable session (instead of a single
+   * presigned PUT) when `size` meets this threshold. Default 100 MiB.
+   */
+  multipartThresholdBytes?: number;
+  /**
+   * Host seams merged via arc's slot-aware `mergeResourceConfig` (2.21) — a
+   * value, or a FACTORY taking the bound engine.
+   *
+   * The factory form exists because host seams routinely wrap the engine's own
+   * repositories (be-prod's extension routes take `repositories.media`), and
+   * under a `blueprint` source the engine does not exist at composition. Arc
+   * evaluates this in the resource phase.
+   */
+  seams?: ResourceSeams | ((engine: TEngine) => ResourceSeams);
+}
+interface MediaModuleDeps<TEngine extends MediaEngineLike = MediaEngineLike> extends Omit<MediaResourceDeps<TEngine>, 'engine'> {
+  /**
+   * Where the engine comes from, and therefore WHO CLOSES IT. Prefer
+   * `blueprint` — the module then binds at bootstrap and the host keeps no
+   * engine singleton at all.
+   */
+  source?: MediaEngineSource<TEngine>;
+  /** Pre-built engine (equivalent to `source: { kind: 'external' }`). */
+  engine?: TEngine;
+  /**
+   * Slot shared with the host, so host code can read the bound engine without
+   * a hand-rolled ensure/get/clear trio. spine-kit owns the primitive.
+   */
+  slot?: EngineSlot<TEngine>;
+  /** Post-registration wiring the HOST owns (event subscriptions, etc.). */
+  /**
+   * Derived from arc rather than re-declared. Arc's `afterResources` may return
+   * a `ModuleDisposer` so the wiring it sets up can be torn down; a hand-written
+   * `=> void` signature silently stops matching the moment that contract moves,
+   * which is exactly how this drifted.
+   */
+  afterResources?: ArcModule['afterResources'];
+  /**
+   * Maintenance sweep intervals. Omit for the sane defaults (hourly stale-pending
+   * + expired, daily soft-delete purge). Pass `false` to opt OUT of the arm
+   * entirely (a host running its own maintenance runner). See
+   * `mediaMaintenanceSchedules`.
+   */
+  maintenance?: MediaMaintenanceOptions | false;
+  dependsOn?: readonly string[];
+}
+declare function createMediaResource(deps: MediaResourceDeps): import("@classytic/arc").ResourceDefinition<import("@classytic/arc").AnyRecord>;
+declare function createMediaModule<TEngine extends MediaEngineLike>(deps: MediaModuleDeps<TEngine>): ArcModule<unknown>;
+interface MediaMaintenanceOptions {
+  /** Sweep pending docs older than the kernel's 24h cutoff. Default hourly. */
+  stalePendingEvery?: number;
+  /** Purge soft-deleted docs past their TTL. Default daily. */
+  purgeDeletedEvery?: number;
+  /** Purge time-bound (`expiresAt`) assets. Default hourly. */
+  purgeExpiredEvery?: number;
+}
+/**
+ * Maintenance schedule definitions for arc's `schedulesPlugin` — drop into
+ * the host's schedule table (with a `lock` for multi-replica leader safety):
+ *
+ * ```ts
+ * await app.register(schedulesPlugin, {
+ *   lock: createMongoLockAdapter({ connection }),
+ *   schedules: [...mediaMaintenanceSchedules(engine), ...otherJobs],
+ * });
+ * ```
+ *
+ * ## What these sweeps do NOT cover — read before relying on them
+ *
+ * An abandoned TWO-PHASE upload leaves **no database row at all**. `start-write`
+ * only signs a URL; the record is created by `complete-write`. So a client that
+ * presigns and then never confirms leaves an object in the bucket that nothing
+ * here can see, let alone reclaim.
+ *
+ * This docblock previously said those uploads "leave `pending` docs that these
+ * sweeps reclaim", and treated bucket lifecycle as belt-and-braces. That was
+ * backwards, and it is the dangerous direction to be wrong in: a deployment
+ * reading it would skip the lifecycle rule and accumulate unreferenced objects
+ * it is still paying to store, with a maintenance job reporting success the
+ * whole time.
+ *
+ * **A bucket lifecycle expiry on incomplete/unreferenced keys is REQUIRED, not
+ * optional.** See media-kit's README ("Orphaned storage objects").
+ *
+ * What these sweeps genuinely reclaim: rows that DO exist and are stuck —
+ * `pending` records from the buffered upload path, soft-deleted docs past their
+ * retention window, and expired assets.
+ */
+declare function mediaMaintenanceSchedules(engine: Pick<MediaEngineLike, 'repositories'>, options?: MediaMaintenanceOptions): ScheduleDefinition[];
+//#endregion
+export { type CompleteMultipartInput, type ConfirmUploadInput, type MediaCleanupStepsOptions, MediaEngineLike, MediaEngineSource, MediaMaintenanceOptions, MediaModuleDeps, MediaPermissions, MediaResourceDeps, type MultipartUploadSession, PermissionGate, type PresignedUploadResult, StartWriteBody, StartWriteResult, createMediaEngineSlot, createMediaModule, createMediaResource, createMediaRolePermissions, mediaCleanupSteps, mediaMaintenanceSchedules };