@vouchington/media 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @vouchington/media
+
+Schema-less direct media upload orchestration for Node.js. Applications provide identifiers,
+object keys, persistence, authorization, lifecycle policy, queues, metadata extraction, and
+failure reporting. The optional `@vouchington/media/s3` entrypoint supplies an S3 adapter with an
+injected client and bucket.
+
+Duplicate reuse/rejection is orchestrated directly. Replacement is an injected atomic operation so
+an application can make the incoming record durable before retiring valid existing media.
+
+This first release handles caller-uploaded objects only. Remote URL ingestion, HTTP fetching,
+image transformation, and video processing are deliberately outside its scope. Compose metadata
+processing with `@vouchington/image-resize` when Sharp-backed inspection is needed.
+
+```ts
+import { createMediaUpload } from '@vouchington/media'
+import { createS3MediaStorage } from '@vouchington/media/s3'
+
+const storage = createS3MediaStorage({ client, bucket: process.env.UPLOAD_BUCKET! })
+const upload = await createMediaUpload(
+  { contentType: request.headers.get('content-type'), contentLength: 42 },
+  {
+    policy: { acceptsContentType: (type) => type.startsWith('image/'), maxBytes: 50_000_000 },
+    createId: crypto.randomUUID,
+    createObjectKey: (id) => `pending/${id}`,
+    expiresInSeconds: 3_600,
+    presignUpload: ({ key, contentType, expiresInSeconds }) =>
+      storage.presignUpload({ key, contentType, expiresInSeconds }),
+    savePending: saveUpload,
+  },
+)
+```
+
+No bucket name, CDN URL, MIME allowlist, size limit, expiry, database schema, authorization rule,
+moderation decision, or queue policy is built in.
+
+The declared upload length is a request and signing input; it does not independently
+prove the stored object's final size. Applications that require that guarantee should verify object
+metadata during completion.
+
+The S3 adapter signs uploads with `If-None-Match: *` so an accepted object key cannot be
+overwritten by reusing its URL. Upload clients must send that header, and bucket CORS policy must
+allow it.

package/dist/cleanup.d.mts

@@ -0,0 +1,12 @@
+export interface CleanupAbandonedMediaDependencies<Record> {
+    deleteObjects(records: readonly Record[]): Promise<void>;
+    deleteRecords(records: readonly Record[]): Promise<void>;
+    findAbandoned(): Promise<readonly Record[]>;
+    onDatabaseError?: (error: unknown, records: readonly Record[]) => Promise<void>;
+    onStorageError?: (error: unknown, records: readonly Record[]) => Promise<void>;
+}
+export interface CleanupAbandonedMediaResult {
+    deletedRecords: number;
+    storageDeleted: boolean;
+}
+export declare function cleanupAbandonedMedia<Record>(dependencies: CleanupAbandonedMediaDependencies<Record>): Promise<CleanupAbandonedMediaResult>;

package/dist/cleanup.mjs

@@ -0,0 +1,31 @@
+export async function cleanupAbandonedMedia(dependencies) {
+    const records = await dependencies.findAbandoned();
+    if (records.length === 0)
+        return { deletedRecords: 0, storageDeleted: true };
+    let storageDeleted = true;
+    try {
+        await dependencies.deleteObjects(records);
+    }
+    catch (error) {
+        storageDeleted = false;
+        try {
+            await dependencies.onStorageError?.(error, records);
+        }
+        catch {
+            // Continue with database cleanup even when storage reporting fails.
+        }
+    }
+    try {
+        await dependencies.deleteRecords(records);
+    }
+    catch (error) {
+        try {
+            await dependencies.onDatabaseError?.(error, records);
+        }
+        catch {
+            // Preserve the database error; reporting is best effort.
+        }
+        throw error;
+    }
+    return { deletedRecords: records.length, storageDeleted };
+}

package/dist/complete-upload.d.mts

@@ -0,0 +1,26 @@
+import type { MediaBody } from './types.mts';
+export type DuplicateMediaDecision = 'reject' | 'replace' | 'reuse';
+export type PersistDigestResult<Record> = {
+    kind: 'saved';
+    record: Record;
+} | {
+    kind: 'conflict';
+    record: Record;
+};
+export interface CompleteMediaUploadDependencies<Record> {
+    authorize(record: Record): boolean | Promise<boolean>;
+    canComplete(record: Record): boolean;
+    claim(id: string): Promise<Record | null>;
+    deleteMedia(record: Record): Promise<void>;
+    enqueueMetadata(record: Record): Promise<void>;
+    findByDigest(digest: string): Promise<Record | null>;
+    getObjectKey(record: Record): string;
+    load(id: string): Promise<Record | null>;
+    markFailed(record: Record, error: unknown): Promise<void>;
+    onDuplicate(existing: Record, incoming: Record): DuplicateMediaDecision;
+    persistDigest(id: string, digest: string): Promise<PersistDigestResult<Record>>;
+    readObject(key: string): Promise<MediaBody>;
+    /** Atomically makes the incoming record durable before retiring the existing media. */
+    replaceDuplicate(existing: Record, incoming: Record, digest: string): Promise<Record>;
+}
+export declare function completeMediaUpload<Record>(id: string, dependencies: CompleteMediaUploadDependencies<Record>): Promise<Record>;

package/dist/complete-upload.mjs

@@ -0,0 +1,51 @@
+import { MediaError } from './errors.mjs';
+import { hashMediaBody } from './streams.mjs';
+export async function completeMediaUpload(id, dependencies) {
+    const loaded = await dependencies.load(id);
+    if (loaded === null)
+        throw new MediaError('MEDIA_NOT_FOUND', 'The media upload was not found');
+    if (!(await dependencies.authorize(loaded))) {
+        throw new MediaError('UNAUTHORIZED', 'The media upload is not authorized');
+    }
+    if (!dependencies.canComplete(loaded)) {
+        throw new MediaError('INVALID_STATE', 'The media upload cannot be completed in its state');
+    }
+    const incoming = await dependencies.claim(id);
+    if (incoming === null)
+        throw new MediaError('INVALID_STATE', 'The media upload was already claimed');
+    try {
+        const body = await dependencies.readObject(dependencies.getObjectKey(incoming));
+        const digest = await hashMediaBody(body);
+        const duplicate = await dependencies.findByDigest(digest);
+        if (duplicate !== null) {
+            return await resolveDuplicate(duplicate, incoming, digest, dependencies);
+        }
+        const result = await dependencies.persistDigest(id, digest);
+        if (result.kind === 'conflict') {
+            return await resolveDuplicate(result.record, incoming, digest, dependencies);
+        }
+        await dependencies.enqueueMetadata(result.record);
+        return result.record;
+    }
+    catch (error) {
+        try {
+            await dependencies.markFailed(incoming, error);
+        }
+        catch {
+            // Preserve the workflow error; failure reporting is best effort.
+        }
+        throw error;
+    }
+}
+async function resolveDuplicate(existing, incoming, digest, dependencies) {
+    const decision = dependencies.onDuplicate(existing, incoming);
+    if (decision === 'replace') {
+        const replacement = await dependencies.replaceDuplicate(existing, incoming, digest);
+        await dependencies.enqueueMetadata(replacement);
+        return replacement;
+    }
+    await dependencies.deleteMedia(incoming);
+    if (decision === 'reuse')
+        return existing;
+    throw new MediaError('DUPLICATE_MEDIA', 'The media duplicates an existing object');
+}

package/dist/create-upload.d.mts

@@ -0,0 +1,17 @@
+import type { CreatedMediaUpload, MediaUploadPolicy, PendingMediaUpload } from './types.mts';
+import { type MediaUploadInput } from './validation.mts';
+export interface CreateMediaUploadDependencies<Record> {
+    createId(): string;
+    createObjectKey(id: string): string;
+    expiresInSeconds: number;
+    now?: () => Date;
+    policy: MediaUploadPolicy;
+    presignUpload(input: {
+        contentLength: number;
+        contentType: string;
+        expiresInSeconds: number;
+        key: string;
+    }): Promise<string>;
+    savePending(upload: PendingMediaUpload): Promise<Record>;
+}
+export declare function createMediaUpload<Record>(input: MediaUploadInput, dependencies: CreateMediaUploadDependencies<Record>): Promise<CreatedMediaUpload<Record>>;

package/dist/create-upload.mjs

@@ -0,0 +1,17 @@
+import { MediaError } from './errors.mjs';
+import { validateMediaUpload } from './validation.mjs';
+export async function createMediaUpload(input, dependencies) {
+    const validated = validateMediaUpload(input, dependencies.policy);
+    const id = dependencies.createId();
+    const key = dependencies.createObjectKey(id);
+    const { expiresInSeconds } = dependencies;
+    if (!Number.isSafeInteger(expiresInSeconds) || expiresInSeconds <= 0) {
+        throw new MediaError('EXPIRY_INVALID', 'The upload expiry must be a positive safe integer');
+    }
+    const now = dependencies.now?.() ?? new Date();
+    const pending = { ...validated, id, key };
+    const uploadUrl = await dependencies.presignUpload({ ...pending, expiresInSeconds });
+    const record = await dependencies.savePending(pending);
+    const expiresAt = new Date(now.getTime() + expiresInSeconds * 1_000);
+    return { ...pending, expiresAt, record, uploadUrl };
+}

package/dist/errors.d.mts

@@ -0,0 +1,5 @@
+export type MediaErrorCode = 'CONTENT_LENGTH_INVALID' | 'CONTENT_TYPE_INVALID' | 'DUPLICATE_MEDIA' | 'EXPIRY_INVALID' | 'INVALID_STATE' | 'MEDIA_NOT_FOUND' | 'POLICY_INVALID' | 'UNAUTHORIZED';
+export declare class MediaError extends Error {
+    readonly code: MediaErrorCode;
+    constructor(code: MediaErrorCode, message: string, options?: ErrorOptions);
+}

package/dist/errors.mjs

@@ -0,0 +1,8 @@
+export class MediaError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'MediaError';
+        this.code = code;
+    }
+}

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+export * from './cleanup.mts';
+export * from './complete-upload.mts';
+export * from './create-upload.mts';
+export * from './errors.mts';
+export * from './metadata.mts';
+export * from './streams.mts';
+export * from './types.mts';
+export * from './validation.mts';

package/dist/index.mjs

@@ -0,0 +1,8 @@
+export * from './cleanup.mjs';
+export * from './complete-upload.mjs';
+export * from './create-upload.mjs';
+export * from './errors.mjs';
+export * from './metadata.mjs';
+export * from './streams.mjs';
+export * from './types.mjs';
+export * from './validation.mjs';

package/dist/metadata.d.mts

@@ -0,0 +1,15 @@
+import type { MediaBody } from './types.mts';
+export interface ProcessMediaMetadataDependencies<Record, Metadata> {
+    canProcess(record: Record): boolean;
+    extractMetadata(path: string): Promise<Metadata>;
+    finalize(record: Record, metadata: Metadata): Promise<Record | null>;
+    getObjectKey(record: Record): string;
+    load(id: string): Promise<Record | null>;
+    markFailed(record: Record, error: unknown): Promise<void>;
+    onFailed?: (record: Record, error: unknown) => Promise<void>;
+    onFinalized?: (record: Record) => Promise<void>;
+    onPostFinalizeError?: (error: unknown, record: Record) => Promise<void>;
+    readObject(key: string): Promise<MediaBody>;
+    validateMetadata?: (metadata: Metadata, record: Record) => void | Promise<void>;
+}
+export declare function processMediaMetadata<Record, Metadata>(id: string, dependencies: ProcessMediaMetadataDependencies<Record, Metadata>): Promise<Record | null>;

package/dist/metadata.mjs

@@ -0,0 +1,41 @@
+import { withTemporaryMediaFile } from './streams.mjs';
+export async function processMediaMetadata(id, dependencies) {
+    const record = await dependencies.load(id);
+    if (record === null)
+        return null;
+    if (!dependencies.canProcess(record))
+        return null;
+    try {
+        const body = await dependencies.readObject(dependencies.getObjectKey(record));
+        const metadata = await withTemporaryMediaFile(body, (path) => dependencies.extractMetadata(path));
+        await dependencies.validateMetadata?.(metadata, record);
+        const finalized = await dependencies.finalize(record, metadata);
+        if (finalized === null)
+            return null;
+        await runPostFinalize(finalized, dependencies);
+        return finalized;
+    }
+    catch (error) {
+        try {
+            await dependencies.markFailed(record, error);
+            await dependencies.onFailed?.(record, error);
+        }
+        catch {
+            // Preserve the processing error; failure reporting is best effort.
+        }
+        throw error;
+    }
+}
+async function runPostFinalize(record, dependencies) {
+    try {
+        await dependencies.onFinalized?.(record);
+    }
+    catch (error) {
+        try {
+            await dependencies.onPostFinalizeError?.(error, record);
+        }
+        catch {
+            // Completion is durable; post-finalize reporting must not undo it.
+        }
+    }
+}

package/dist/s3.d.mts

@@ -0,0 +1,33 @@
+import { PutObjectCommand, type S3Client } from '@aws-sdk/client-s3';
+import type { MediaBody } from './types.mts';
+export interface S3MediaStorageOptions {
+    bucket: string;
+    client: S3Client;
+    sign?: (client: S3Client, command: PutObjectCommand, options: {
+        expiresIn: number;
+    }) => Promise<string>;
+}
+export interface S3MediaStorage {
+    deleteObject(key: string): Promise<void>;
+    deleteObjects(keys: readonly string[]): Promise<void>;
+    getObject(key: string): Promise<MediaBody>;
+    presignUpload(input: {
+        contentLength?: number;
+        contentType: string;
+        expiresInSeconds: number;
+        key: string;
+    }): Promise<string>;
+}
+export type S3MediaDeleteFailure = {
+    cause: unknown;
+    keys: readonly string[];
+} | {
+    code?: string;
+    key?: string;
+    message?: string;
+};
+export declare class S3MediaDeleteError extends Error {
+    readonly failures: readonly S3MediaDeleteFailure[];
+    constructor(failures: readonly S3MediaDeleteFailure[]);
+}
+export declare function createS3MediaStorage(options: S3MediaStorageOptions): S3MediaStorage;

package/dist/s3.mjs

@@ -0,0 +1,65 @@
+import { DeleteObjectCommand, DeleteObjectsCommand, GetObjectCommand, PutObjectCommand, } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+export class S3MediaDeleteError extends Error {
+    failures;
+    constructor(failures) {
+        super(`S3 failed to delete ${failures.length} media object(s)`);
+        this.name = 'S3MediaDeleteError';
+        this.failures = failures;
+    }
+}
+export function createS3MediaStorage(options) {
+    const sign = options.sign ?? ((client, command, signOptions) => getSignedUrl(client, command, signOptions));
+    return {
+        async presignUpload(input) {
+            const command = new PutObjectCommand({
+                Bucket: options.bucket,
+                Key: input.key,
+                ContentLength: input.contentLength,
+                ContentType: input.contentType,
+                IfNoneMatch: '*',
+            });
+            return sign(options.client, command, { expiresIn: input.expiresInSeconds });
+        },
+        async getObject(key) {
+            const output = await options.client.send(new GetObjectCommand({ Bucket: options.bucket, Key: key }));
+            const body = output.Body;
+            const iterator = typeof body === 'object' && body !== null
+                ? body[Symbol.asyncIterator]
+                : undefined;
+            if (typeof iterator !== 'function') {
+                throw new TypeError('S3 returned an unreadable media body');
+            }
+            return body;
+        },
+        async deleteObject(key) {
+            await options.client.send(new DeleteObjectCommand({ Bucket: options.bucket, Key: key }));
+        },
+        async deleteObjects(keys) {
+            const failures = [];
+            for (let index = 0; index < keys.length; index += 1_000) {
+                const batch = keys.slice(index, index + 1_000);
+                let output;
+                try {
+                    output = await options.client.send(new DeleteObjectsCommand({
+                        Bucket: options.bucket,
+                        Delete: { Objects: batch.map((Key) => ({ Key })), Quiet: true },
+                    }));
+                }
+                catch (cause) {
+                    failures.push({ cause, keys: batch });
+                    continue;
+                }
+                for (const failure of output.Errors ?? []) {
+                    failures.push({
+                        ...(failure.Code === undefined ? {} : { code: failure.Code }),
+                        ...(failure.Key === undefined ? {} : { key: failure.Key }),
+                        ...(failure.Message === undefined ? {} : { message: failure.Message }),
+                    });
+                }
+            }
+            if (failures.length > 0)
+                throw new S3MediaDeleteError(failures);
+        },
+    };
+}

package/dist/streams.d.mts

@@ -0,0 +1,3 @@
+import type { MediaBody } from './types.mts';
+export declare function hashMediaBody(body: MediaBody, algorithm?: string): Promise<string>;
+export declare function withTemporaryMediaFile<Result>(body: MediaBody, useFile: (path: string) => Promise<Result>): Promise<Result>;

package/dist/streams.mjs

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+export async function hashMediaBody(body, algorithm = 'sha256') {
+    const hash = createHash(algorithm);
+    for await (const chunk of body)
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+export async function withTemporaryMediaFile(body, useFile) {
+    const directory = await mkdtemp(join(tmpdir(), 'vouchington-media-'));
+    const path = join(directory, 'media');
+    try {
+        await pipeline(body, createWriteStream(path, { flags: 'wx' }));
+        return await useFile(path);
+    }
+    finally {
+        await rm(directory, { force: true, recursive: true });
+    }
+}

package/dist/types.d.mts

@@ -0,0 +1,21 @@
+export interface MediaUploadPolicy {
+    acceptsContentType(contentType: string): boolean;
+    maxBytes: number;
+    minBytes?: number;
+}
+export interface ValidatedMediaUpload {
+    contentLength: number;
+    contentType: string;
+}
+export type MediaBody = AsyncIterable<Uint8Array>;
+export interface PendingMediaUpload {
+    contentLength: number;
+    contentType: string;
+    id: string;
+    key: string;
+}
+export interface CreatedMediaUpload<Record> extends PendingMediaUpload {
+    expiresAt: Date;
+    record: Record;
+    uploadUrl: string;
+}

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.mts

@@ -0,0 +1,6 @@
+import type { MediaUploadPolicy, ValidatedMediaUpload } from './types.mts';
+export interface MediaUploadInput {
+    contentLength: number | null | undefined;
+    contentType: string | null | undefined;
+}
+export declare function validateMediaUpload(input: MediaUploadInput, policy: MediaUploadPolicy): ValidatedMediaUpload;

package/dist/validation.mjs

@@ -0,0 +1,25 @@
+import { MediaError } from './errors.mjs';
+export function validateMediaUpload(input, policy) {
+    const contentType = input.contentType?.split(';', 1)[0]?.trim().toLowerCase();
+    if (contentType === undefined ||
+        !/^[a-z0-9!#$%&'*+.^_`|~-]+\/[a-z0-9!#$%&'*+.^_`|~-]+$/.test(contentType) ||
+        !policy.acceptsContentType(contentType)) {
+        throw new MediaError('CONTENT_TYPE_INVALID', 'The media content type is not accepted');
+    }
+    const contentLength = input.contentLength;
+    const minimum = policy.minBytes ?? 1;
+    if (!Number.isSafeInteger(minimum) ||
+        minimum < 0 ||
+        !Number.isSafeInteger(policy.maxBytes) ||
+        policy.maxBytes < minimum) {
+        throw new MediaError('POLICY_INVALID', 'Media size policy bounds must be safe integers');
+    }
+    if (contentLength === null ||
+        contentLength === undefined ||
+        !Number.isSafeInteger(contentLength) ||
+        contentLength < minimum ||
+        contentLength > policy.maxBytes) {
+        throw new MediaError('CONTENT_LENGTH_INVALID', 'The media content length is not accepted');
+    }
+    return { contentLength, contentType };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@vouchington/media",
+  "version": "0.0.0",
+  "description": "Schema-less direct media upload orchestration and S3 storage primitives.",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/media#readme",
+  "bugs": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/media"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./s3": {
+      "types": "./dist/s3.d.mts",
+      "import": "./dist/s3.mjs",
+      "default": "./dist/s3.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1121.0",
+    "@aws-sdk/s3-request-presigner": "^3.1121.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}