@sproux/media-sdk 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# @sproux/media-sdk
+
+Media URL builder library for Sproux — build image variant URLs, video HLS playlist URLs, and thumbnails from original media URLs.
+
+## Installation
+
+```bash
+# npm
+npm install @sproux/media-sdk
+
+# pnpm
+pnpm add @sproux/media-sdk
+
+# yarn
+yarn add @sproux/media-sdk
+```
+
+## Quick Start
+
+```typescript
+import {
+  buildImageVariantUrl,
+  buildVideoHlsUrl,
+  buildVideoThumbnailUrl,
+  parseMediaUrl,
+} from '@sproux/media-sdk';
+
+// Build an image variant URL
+const imageUrl = buildImageVariantUrl(
+  'https://cdn.example.com/avatar/image/usr-1/profile.jpg',
+  { width: 200, height: 200, resizeType: 'fit', quality: 80 }
+);
+// → "https://cdn.example.com/avatar/image/usr-1/profile-200x200-fit-q80.webp"
+
+// Build a video HLS playlist URL
+const hlsUrl = buildVideoHlsUrl(
+  'https://cdn.example.com/gallery/video/usr-1/intro.mp4'
+);
+// → "https://cdn.example.com/gallery/video/usr-1/intro/playlist.m3u8"
+
+// Build a video thumbnail URL
+const thumbnailUrl = buildVideoThumbnailUrl(
+  'https://cdn.example.com/gallery/video/usr-1/intro.mp4'
+);
+// → "https://cdn.example.com/gallery/video/usr-1/intro/thumbnail.webp"
+```
+
+## API Reference
+
+### `parseMediaUrl(url: string): ParsedMediaUrl`
+
+Parse a media URL into its structured components.
+
+**Expected URL pattern:** `{cdnBase}/{purpose}/{type}/{userId}/{name}.{extension}`
+
+```typescript
+import { parseMediaUrl } from '@sproux/media-sdk';
+
+const parsed = parseMediaUrl('https://cdn.example.com/avatar/image/usr-1/abc.jpg');
+// {
+//   originalUrl: "https://cdn.example.com/avatar/image/usr-1/abc.jpg",
+//   cdnBase: "https://cdn.example.com",
+//   objectKey: "avatar/image/usr-1/abc.jpg",
+//   purpose: "avatar",
+//   type: "image",
+//   userId: "usr-1",
+//   name: "abc",
+//   extension: "jpg"
+// }
+```
+
+### `buildImageVariantUrl(originalUrl: string, options: ImageVariantOptions): string`
+
+Build a CDN URL for an image variant with specific dimensions, resize type, and quality.
+
+```typescript
+import { buildImageVariantUrl } from '@sproux/media-sdk';
+
+const url = buildImageVariantUrl(
+  'https://cdn.example.com/avatar/image/usr-1/photo.jpg',
+  {
+    width: 400,
+    height: 300,
+    resizeType: 'fill',
+    format: 'webp',  // optional, defaults to 'webp'
+    quality: 85,     // optional
+  }
+);
+// → "https://cdn.example.com/avatar/image/usr-1/photo-400x300-fill-q85.webp"
+```
+
+#### ImageVariantOptions
+
+| Property     | Type              | Required | Description                           |
+| ------------ | ----------------- | -------- | ------------------------------------- |
+| `width`      | `number`          | Yes      | Target width in pixels (1-4096)       |
+| `height`     | `number`          | Yes      | Target height in pixels (1-4096)      |
+| `resizeType` | `ImageResizeType` | Yes      | Resize strategy: `fit`, `fill`, `auto` |
+| `format`     | `ImageFormat`     | No       | Output format (default: `webp`)       |
+| `quality`    | `number`          | No       | Quality 1-100                         |
+
+### `buildVideoHlsUrl(originalUrl: string): string`
+
+Build an HLS playlist URL from an original video URL.
+
+```typescript
+import { buildVideoHlsUrl } from '@sproux/media-sdk';
+
+const hlsUrl = buildVideoHlsUrl(
+  'https://cdn.example.com/gallery/video/usr-1/video.mp4'
+);
+// → "https://cdn.example.com/gallery/video/usr-1/video/playlist.m3u8"
+```
+
+### `buildVideoThumbnailUrl(originalUrl: string): string`
+
+Build a thumbnail URL from an original video URL.
+
+```typescript
+import { buildVideoThumbnailUrl } from '@sproux/media-sdk';
+
+const thumbnailUrl = buildVideoThumbnailUrl(
+  'https://cdn.example.com/gallery/video/usr-1/video.mp4'
+);
+// → "https://cdn.example.com/gallery/video/usr-1/video/thumbnail.webp"
+```
+
+### `buildVariantString(options: ImageVariantOptions): string`
+
+Build a deterministic variant string from image variant options. This is used internally by `buildImageVariantUrl`.
+
+```typescript
+import { buildVariantString } from '@sproux/media-sdk';
+
+buildVariantString({ width: 200, height: 200, resizeType: 'fit' });
+// → "200x200-fit"
+
+buildVariantString({ width: 200, height: 200, resizeType: 'fit', quality: 80 });
+// → "200x200-fit-q80"
+```
+
+## Constants
+
+The SDK exports constants for type-safe usage:
+
+```typescript
+import {
+  MEDIA_TYPE,       // { IMAGE: 'image', VIDEO: 'video' }
+  MEDIA_PURPOSE,    // { AVATAR: 'avatar', HERO: 'hero', GALLERY: 'gallery' }
+  MEDIA_STATUS,     // { PENDING, UPLOADED, PROCESSING, READY, ERROR }
+  IMAGE_FORMAT,     // { WEBP, AVIF, JPEG, PNG, JPG }
+  IMAGE_RESIZE_TYPE // { FIT, FILL, AUTO }
+} from '@sproux/media-sdk';
+```
+
+## Types
+
+```typescript
+import type {
+  MediaType,           // 'image' | 'video'
+  MediaPurpose,        // 'avatar' | 'hero' | 'gallery'
+  MediaStatus,         // 'pending' | 'uploaded' | 'processing' | 'ready' | 'error'
+  ImageFormat,         // 'webp' | 'avif' | 'jpeg' | 'png' | 'jpg'
+  ImageResizeType,     // 'fit' | 'fill' | 'auto'
+  ParsedMediaUrl,
+  ImageVariantOptions,
+} from '@sproux/media-sdk';
+```
+
+## URL Structure
+
+This SDK expects media URLs to follow this structure:
+
+```
+{cdnBase}/{purpose}/{type}/{userId}/{filename}
+```
+
+| Segment    | Description                               | Valid Values                      |
+| ---------- | ----------------------------------------- | --------------------------------- |
+| `cdnBase`  | CDN origin including protocol             | Any valid URL origin              |
+| `purpose`  | Media use case                            | `avatar`, `hero`, `gallery`       |
+| `type`     | Media type                                | `image`, `video`                  |
+| `userId`   | User identifier                           | Any string                        |
+| `filename` | File name with extension                  | `{name}.{extension}`              |
+
+### Image Variant URL Structure
+
+```
+{cdnBase}/{purpose}/image/{userId}/{name}-{width}x{height}-{resizeType}[-q{quality}].{format}
+```
+
+Example: `https://cdn.example.com/avatar/image/usr-1/photo-200x200-fit-q80.webp`
+
+### Video HLS URL Structure
+
+```
+{cdnBase}/{purpose}/video/{userId}/{name}/playlist.m3u8
+```
+
+### Video Thumbnail URL Structure
+
+```
+{cdnBase}/{purpose}/video/{userId}/{name}/thumbnail.webp
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  IMAGE_FORMAT: () => IMAGE_FORMAT,
+  IMAGE_RESIZE_TYPE: () => IMAGE_RESIZE_TYPE,
+  MEDIA_DEFAULTS: () => MEDIA_DEFAULTS,
+  MEDIA_PURPOSE: () => MEDIA_PURPOSE,
+  MEDIA_STATUS: () => MEDIA_STATUS,
+  MEDIA_TYPE: () => MEDIA_TYPE,
+  R2_PATH: () => R2_PATH,
+  buildImageVariantUrl: () => buildImageVariantUrl,
+  buildVariantString: () => buildVariantString,
+  buildVideoHlsUrl: () => buildVideoHlsUrl,
+  buildVideoThumbnailUrl: () => buildVideoThumbnailUrl,
+  parseMediaUrl: () => parseMediaUrl
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/constants.ts
+var MEDIA_TYPE = {
+  IMAGE: "image",
+  VIDEO: "video"
+};
+var MEDIA_PURPOSE = {
+  AVATAR: "avatar",
+  HERO: "hero",
+  GALLERY: "gallery"
+};
+var MEDIA_STATUS = {
+  PENDING: "pending",
+  UPLOADED: "uploaded",
+  PROCESSING: "processing",
+  READY: "ready",
+  ERROR: "error"
+};
+var IMAGE_FORMAT = {
+  WEBP: "webp",
+  AVIF: "avif",
+  JPEG: "jpeg",
+  PNG: "png",
+  JPG: "jpg"
+};
+var IMAGE_RESIZE_TYPE = {
+  FIT: "fit",
+  FILL: "fill",
+  AUTO: "auto"
+};
+var R2_PATH = {
+  HLS_PLAYLIST: "playlist.m3u8",
+  THUMBNAIL: "thumbnail.webp"
+};
+var MEDIA_DEFAULTS = {
+  IMAGE_FORMAT: IMAGE_FORMAT.WEBP
+};
+
+// src/parse-media-url.ts
+var VALID_PURPOSES = new Set(Object.values(MEDIA_PURPOSE));
+var VALID_TYPES = new Set(Object.values(MEDIA_TYPE));
+function parseMediaUrl(originalUrl) {
+  let url;
+  try {
+    url = new URL(originalUrl);
+  } catch {
+    throw new Error(`Invalid media URL: "${originalUrl}"`);
+  }
+  const pathname = url.pathname.startsWith("/") ? url.pathname.slice(1) : url.pathname;
+  const segments = pathname.split("/");
+  if (segments.length < 4) {
+    throw new Error(
+      `Invalid media URL path: expected at least 4 segments (purpose/type/userId/filename), got ${segments.length} in "${pathname}"`
+    );
+  }
+  const [purpose, type, userId, filename] = segments;
+  if (!VALID_PURPOSES.has(purpose)) {
+    throw new Error(
+      `Invalid media purpose: "${purpose}". Expected one of: ${[...VALID_PURPOSES].join(", ")}`
+    );
+  }
+  if (!VALID_TYPES.has(type)) {
+    throw new Error(
+      `Invalid media type: "${type}". Expected one of: ${[...VALID_TYPES].join(", ")}`
+    );
+  }
+  if (!userId) {
+    throw new Error("Missing userId segment in media URL");
+  }
+  if (!filename) {
+    throw new Error("Missing filename segment in media URL");
+  }
+  const dotIndex = filename.lastIndexOf(".");
+  if (dotIndex <= 0) {
+    throw new Error(`Invalid filename: "${filename}". Expected format: "name.extension"`);
+  }
+  const name = filename.slice(0, dotIndex);
+  const extension = filename.slice(dotIndex + 1);
+  if (!extension) {
+    throw new Error(`Missing file extension in filename: "${filename}"`);
+  }
+  const cdnBase = `${url.protocol}//${url.host}`;
+  const objectKey = pathname;
+  return {
+    originalUrl,
+    cdnBase,
+    objectKey,
+    purpose,
+    type,
+    userId,
+    name,
+    extension
+  };
+}
+
+// src/build-variant-string.ts
+function buildVariantString(options) {
+  validateVariantOptions(options);
+  const parts = [`${options.width}x${options.height}`, options.resizeType];
+  if (options.quality != null) {
+    parts.push(`q${options.quality}`);
+  }
+  return parts.join("-");
+}
+function validateVariantOptions(options) {
+  if (!Number.isInteger(options.width) || options.width < 1 || options.width > 4096) {
+    throw new Error(`Invalid width: ${options.width}. Must be an integer between 1 and 4096.`);
+  }
+  if (!Number.isInteger(options.height) || options.height < 1 || options.height > 4096) {
+    throw new Error(`Invalid height: ${options.height}. Must be an integer between 1 and 4096.`);
+  }
+  if (options.quality != null) {
+    if (!Number.isInteger(options.quality) || options.quality < 1 || options.quality > 100) {
+      throw new Error(
+        `Invalid quality: ${options.quality}. Must be an integer between 1 and 100.`
+      );
+    }
+  }
+}
+
+// src/build-image-variant-url.ts
+function buildImageVariantUrl(originalUrl, options) {
+  const parsed = parseMediaUrl(originalUrl);
+  if (parsed.type !== "image") {
+    throw new Error(`Expected image URL, got type "${parsed.type}" in "${originalUrl}"`);
+  }
+  const variant = buildVariantString(options);
+  const format = options.format ?? MEDIA_DEFAULTS.IMAGE_FORMAT;
+  return `${parsed.cdnBase}/${parsed.purpose}/${parsed.type}/${parsed.userId}/${parsed.name}-${variant}.${format}`;
+}
+
+// src/build-video-hls-url.ts
+function buildVideoHlsUrl(originalUrl) {
+  const parsed = parseMediaUrl(originalUrl);
+  if (parsed.type !== "video") {
+    throw new Error(`Expected video URL, got type "${parsed.type}" in "${originalUrl}"`);
+  }
+  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.HLS_PLAYLIST}`;
+}
+
+// src/build-video-thumbnail-url.ts
+function buildVideoThumbnailUrl(originalUrl) {
+  const parsed = parseMediaUrl(originalUrl);
+  if (parsed.type !== "video") {
+    throw new Error(`Expected video URL, got type "${parsed.type}" in "${originalUrl}"`);
+  }
+  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.THUMBNAIL}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IMAGE_FORMAT,
+  IMAGE_RESIZE_TYPE,
+  MEDIA_DEFAULTS,
+  MEDIA_PURPOSE,
+  MEDIA_STATUS,
+  MEDIA_TYPE,
+  R2_PATH,
+  buildImageVariantUrl,
+  buildVariantString,
+  buildVideoHlsUrl,
+  buildVideoThumbnailUrl,
+  parseMediaUrl
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/constants.ts","../src/parse-media-url.ts","../src/build-variant-string.ts","../src/build-image-variant-url.ts","../src/build-video-hls-url.ts","../src/build-video-thumbnail-url.ts"],"sourcesContent":["// Constants\r\nexport {\r\n  MEDIA_TYPE,\r\n  MEDIA_PURPOSE,\r\n  MEDIA_STATUS,\r\n  IMAGE_FORMAT,\r\n  IMAGE_RESIZE_TYPE,\r\n  R2_PATH,\r\n  MEDIA_DEFAULTS,\r\n} from './constants';\r\n\r\n// Types\r\nexport type {\r\n  MediaType,\r\n  MediaPurpose,\r\n  MediaStatus,\r\n  ImageFormat,\r\n  ImageResizeType,\r\n  ParsedMediaUrl,\r\n  ImageVariantOptions,\r\n} from './types';\r\n\r\n// Functions\r\nexport { parseMediaUrl } from './parse-media-url';\r\nexport { buildVariantString } from './build-variant-string';\r\nexport { buildImageVariantUrl } from './build-image-variant-url';\r\nexport { buildVideoHlsUrl } from './build-video-hls-url';\r\nexport { buildVideoThumbnailUrl } from './build-video-thumbnail-url';\r\n","// ============================================================================\r\n// MEDIA TYPE\r\n// ============================================================================\r\n\r\nexport const MEDIA_TYPE = {\r\n  IMAGE: 'image',\r\n  VIDEO: 'video',\r\n} as const;\r\n\r\n// ============================================================================\r\n// MEDIA PURPOSE\r\n// ============================================================================\r\n\r\nexport const MEDIA_PURPOSE = {\r\n  AVATAR: 'avatar',\r\n  HERO: 'hero',\r\n  GALLERY: 'gallery',\r\n} as const;\r\n\r\n// ============================================================================\r\n// MEDIA STATUS\r\n// ============================================================================\r\n\r\nexport const MEDIA_STATUS = {\r\n  PENDING: 'pending',\r\n  UPLOADED: 'uploaded',\r\n  PROCESSING: 'processing',\r\n  READY: 'ready',\r\n  ERROR: 'error',\r\n} as const;\r\n\r\n// ============================================================================\r\n// IMAGE FORMAT\r\n// ============================================================================\r\n\r\nexport const IMAGE_FORMAT = {\r\n  WEBP: 'webp',\r\n  AVIF: 'avif',\r\n  JPEG: 'jpeg',\r\n  PNG: 'png',\r\n  JPG: 'jpg',\r\n} as const;\r\n\r\n// ============================================================================\r\n// IMAGE RESIZE TYPE\r\n// ============================================================================\r\n\r\nexport const IMAGE_RESIZE_TYPE = {\r\n  FIT: 'fit',\r\n  FILL: 'fill',\r\n  AUTO: 'auto',\r\n} as const;\r\n\r\n// ============================================================================\r\n// R2/CDN PATH CONSTANTS\r\n// ============================================================================\r\n\r\nexport const R2_PATH = {\r\n  HLS_PLAYLIST: 'playlist.m3u8',\r\n  THUMBNAIL: 'thumbnail.webp',\r\n} as const;\r\n\r\n// ============================================================================\r\n// DEFAULTS\r\n// ============================================================================\r\n\r\nexport const MEDIA_DEFAULTS = {\r\n  IMAGE_FORMAT: IMAGE_FORMAT.WEBP,\r\n} as const;\r\n","import { MEDIA_PURPOSE, MEDIA_TYPE } from './constants';\r\nimport type { ParsedMediaUrl, MediaPurpose, MediaType } from './types';\r\n\r\nconst VALID_PURPOSES = new Set<string>(Object.values(MEDIA_PURPOSE));\r\nconst VALID_TYPES = new Set<string>(Object.values(MEDIA_TYPE));\r\n\r\n/**\r\n * Parse a full media URL into structured components.\r\n *\r\n * Expected URL pattern:\r\n *   {cdnBase}/{purpose}/{type}/{userId}/{name}.{extension}\r\n *\r\n * Example:\r\n *   https://cdn.example.com/avatar/image/usr-1/abc.jpg\r\n *   → { cdnBase: \"https://cdn.example.com\", purpose: \"avatar\", type: \"image\", userId: \"usr-1\", name: \"abc\", extension: \"jpg\" }\r\n */\r\nexport function parseMediaUrl(originalUrl: string): ParsedMediaUrl {\r\n  let url: URL;\r\n  try {\r\n    url = new URL(originalUrl);\r\n  } catch {\r\n    throw new Error(`Invalid media URL: \"${originalUrl}\"`);\r\n  }\r\n\r\n  // Remove leading slash and split into segments\r\n  const pathname = url.pathname.startsWith('/') ? url.pathname.slice(1) : url.pathname;\r\n  const segments = pathname.split('/');\r\n\r\n  if (segments.length < 4) {\r\n    throw new Error(\r\n      `Invalid media URL path: expected at least 4 segments (purpose/type/userId/filename), got ${segments.length} in \"${pathname}\"`,\r\n    );\r\n  }\r\n\r\n  const [purpose, type, userId, filename] = segments as [string, string, string, string];\r\n\r\n  if (!VALID_PURPOSES.has(purpose)) {\r\n    throw new Error(\r\n      `Invalid media purpose: \"${purpose}\". Expected one of: ${[...VALID_PURPOSES].join(', ')}`,\r\n    );\r\n  }\r\n\r\n  if (!VALID_TYPES.has(type)) {\r\n    throw new Error(\r\n      `Invalid media type: \"${type}\". Expected one of: ${[...VALID_TYPES].join(', ')}`,\r\n    );\r\n  }\r\n\r\n  if (!userId) {\r\n    throw new Error('Missing userId segment in media URL');\r\n  }\r\n\r\n  if (!filename) {\r\n    throw new Error('Missing filename segment in media URL');\r\n  }\r\n\r\n  const dotIndex = filename.lastIndexOf('.');\r\n  if (dotIndex <= 0) {\r\n    throw new Error(`Invalid filename: \"${filename}\". Expected format: \"name.extension\"`);\r\n  }\r\n\r\n  const name = filename.slice(0, dotIndex);\r\n  const extension = filename.slice(dotIndex + 1);\r\n\r\n  if (!extension) {\r\n    throw new Error(`Missing file extension in filename: \"${filename}\"`);\r\n  }\r\n\r\n  const cdnBase = `${url.protocol}//${url.host}`;\r\n  const objectKey = pathname;\r\n\r\n  return {\r\n    originalUrl,\r\n    cdnBase,\r\n    objectKey,\r\n    purpose: purpose as MediaPurpose,\r\n    type: type as MediaType,\r\n    userId,\r\n    name,\r\n    extension,\r\n  };\r\n}\r\n","import type { ImageVariantOptions } from './types';\r\n\r\n/**\r\n * Build a deterministic variant string from image variant options.\r\n *\r\n * Format: {width}x{height}-{resizeType}[-q{quality}]\r\n *\r\n * Examples:\r\n *   { width: 200, height: 200, resizeType: 'fit' }            → \"200x200-fit\"\r\n *   { width: 200, height: 200, resizeType: 'fit', quality: 80 } → \"200x200-fit-q80\"\r\n */\r\nexport function buildVariantString(options: ImageVariantOptions): string {\r\n  validateVariantOptions(options);\r\n\r\n  const parts: string[] = [`${options.width}x${options.height}`, options.resizeType];\r\n\r\n  if (options.quality != null) {\r\n    parts.push(`q${options.quality}`);\r\n  }\r\n\r\n  return parts.join('-');\r\n}\r\n\r\nfunction validateVariantOptions(options: ImageVariantOptions): void {\r\n  if (!Number.isInteger(options.width) || options.width < 1 || options.width > 4096) {\r\n    throw new Error(`Invalid width: ${options.width}. Must be an integer between 1 and 4096.`);\r\n  }\r\n\r\n  if (!Number.isInteger(options.height) || options.height < 1 || options.height > 4096) {\r\n    throw new Error(`Invalid height: ${options.height}. Must be an integer between 1 and 4096.`);\r\n  }\r\n\r\n  if (options.quality != null) {\r\n    if (!Number.isInteger(options.quality) || options.quality < 1 || options.quality > 100) {\r\n      throw new Error(\r\n        `Invalid quality: ${options.quality}. Must be an integer between 1 and 100.`,\r\n      );\r\n    }\r\n  }\r\n}\r\n","import { MEDIA_DEFAULTS } from './constants';\r\nimport { parseMediaUrl } from './parse-media-url';\r\nimport { buildVariantString } from './build-variant-string';\r\nimport type { ImageVariantOptions } from './types';\r\n\r\n/**\r\n * Build a full CDN URL for an image variant.\r\n *\r\n * Takes an original image URL and variant options, returns the CDN URL\r\n * for that specific variant.\r\n *\r\n * Example:\r\n *   buildImageVariantUrl(\"https://cdn.example.com/avatar/image/usr-1/abc.jpg\", {\r\n *     width: 200, height: 200, resizeType: 'fit', quality: 80\r\n *   })\r\n *   → \"https://cdn.example.com/avatar/image/usr-1/abc-200x200-fit-q80.webp\"\r\n */\r\nexport function buildImageVariantUrl(originalUrl: string, options: ImageVariantOptions): string {\r\n  const parsed = parseMediaUrl(originalUrl);\r\n\r\n  if (parsed.type !== 'image') {\r\n    throw new Error(`Expected image URL, got type \"${parsed.type}\" in \"${originalUrl}\"`);\r\n  }\r\n\r\n  const variant = buildVariantString(options);\r\n  const format = options.format ?? MEDIA_DEFAULTS.IMAGE_FORMAT;\r\n\r\n  return `${parsed.cdnBase}/${parsed.purpose}/${parsed.type}/${parsed.userId}/${parsed.name}-${variant}.${format}`;\r\n}\r\n","import { R2_PATH } from './constants';\r\nimport { parseMediaUrl } from './parse-media-url';\r\n\r\n/**\r\n * Build HLS playlist URL from an original video URL.\r\n *\r\n * Example:\r\n *   buildVideoHlsUrl(\"https://cdn.example.com/gallery/video/usr-1/xyz.mp4\")\r\n *   → \"https://cdn.example.com/gallery/video/usr-1/xyz/playlist.m3u8\"\r\n */\r\nexport function buildVideoHlsUrl(originalUrl: string): string {\r\n  const parsed = parseMediaUrl(originalUrl);\r\n\r\n  if (parsed.type !== 'video') {\r\n    throw new Error(`Expected video URL, got type \"${parsed.type}\" in \"${originalUrl}\"`);\r\n  }\r\n\r\n  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.HLS_PLAYLIST}`;\r\n}\r\n","import { R2_PATH } from './constants';\r\nimport { parseMediaUrl } from './parse-media-url';\r\n\r\n/**\r\n * Build thumbnail URL from an original video URL.\r\n *\r\n * Example:\r\n *   buildVideoThumbnailUrl(\"https://cdn.example.com/gallery/video/usr-1/xyz.mp4\")\r\n *   → \"https://cdn.example.com/gallery/video/usr-1/xyz/thumbnail.webp\"\r\n */\r\nexport function buildVideoThumbnailUrl(originalUrl: string): string {\r\n  const parsed = parseMediaUrl(originalUrl);\r\n\r\n  if (parsed.type !== 'video') {\r\n    throw new Error(`Expected video URL, got type \"${parsed.type}\" in \"${originalUrl}\"`);\r\n  }\r\n\r\n  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.THUMBNAIL}`;\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,128 @@
+declare const MEDIA_TYPE: {
+    readonly IMAGE: "image";
+    readonly VIDEO: "video";
+};
+declare const MEDIA_PURPOSE: {
+    readonly AVATAR: "avatar";
+    readonly HERO: "hero";
+    readonly GALLERY: "gallery";
+};
+declare const MEDIA_STATUS: {
+    readonly PENDING: "pending";
+    readonly UPLOADED: "uploaded";
+    readonly PROCESSING: "processing";
+    readonly READY: "ready";
+    readonly ERROR: "error";
+};
+declare const IMAGE_FORMAT: {
+    readonly WEBP: "webp";
+    readonly AVIF: "avif";
+    readonly JPEG: "jpeg";
+    readonly PNG: "png";
+    readonly JPG: "jpg";
+};
+declare const IMAGE_RESIZE_TYPE: {
+    readonly FIT: "fit";
+    readonly FILL: "fill";
+    readonly AUTO: "auto";
+};
+declare const R2_PATH: {
+    readonly HLS_PLAYLIST: "playlist.m3u8";
+    readonly THUMBNAIL: "thumbnail.webp";
+};
+declare const MEDIA_DEFAULTS: {
+    readonly IMAGE_FORMAT: "webp";
+};
+
+type MediaType = (typeof MEDIA_TYPE)[keyof typeof MEDIA_TYPE];
+type MediaPurpose = (typeof MEDIA_PURPOSE)[keyof typeof MEDIA_PURPOSE];
+type MediaStatus = (typeof MEDIA_STATUS)[keyof typeof MEDIA_STATUS];
+type ImageFormat = (typeof IMAGE_FORMAT)[keyof typeof IMAGE_FORMAT];
+type ImageResizeType = (typeof IMAGE_RESIZE_TYPE)[keyof typeof IMAGE_RESIZE_TYPE];
+interface ParsedMediaUrl {
+    /** Full original URL */
+    originalUrl: string;
+    /** CDN base including protocol and host */
+    cdnBase: string;
+    /** Object key without CDN base */
+    objectKey: string;
+    /** Purpose segment: avatar, hero, gallery */
+    purpose: MediaPurpose;
+    /** Type segment: image, video */
+    type: MediaType;
+    /** User ID segment */
+    userId: string;
+    /** File name without extension */
+    name: string;
+    /** File extension without dot */
+    extension: string;
+}
+interface ImageVariantOptions {
+    /** Target width in pixels (1-4096) */
+    width: number;
+    /** Target height in pixels (1-4096) */
+    height: number;
+    /** Resize type: fit, fill, auto */
+    resizeType: ImageResizeType;
+    /** Output format (default: webp) */
+    format?: ImageFormat;
+    /** Quality 1-100 */
+    quality?: number;
+}
+
+/**
+ * Parse a full media URL into structured components.
+ *
+ * Expected URL pattern:
+ *   {cdnBase}/{purpose}/{type}/{userId}/{name}.{extension}
+ *
+ * Example:
+ *   https://cdn.example.com/avatar/image/usr-1/abc.jpg
+ *   → { cdnBase: "https://cdn.example.com", purpose: "avatar", type: "image", userId: "usr-1", name: "abc", extension: "jpg" }
+ */
+declare function parseMediaUrl(originalUrl: string): ParsedMediaUrl;
+
+/**
+ * Build a deterministic variant string from image variant options.
+ *
+ * Format: {width}x{height}-{resizeType}[-q{quality}]
+ *
+ * Examples:
+ *   { width: 200, height: 200, resizeType: 'fit' }            → "200x200-fit"
+ *   { width: 200, height: 200, resizeType: 'fit', quality: 80 } → "200x200-fit-q80"
+ */
+declare function buildVariantString(options: ImageVariantOptions): string;
+
+/**
+ * Build a full CDN URL for an image variant.
+ *
+ * Takes an original image URL and variant options, returns the CDN URL
+ * for that specific variant.
+ *
+ * Example:
+ *   buildImageVariantUrl("https://cdn.example.com/avatar/image/usr-1/abc.jpg", {
+ *     width: 200, height: 200, resizeType: 'fit', quality: 80
+ *   })
+ *   → "https://cdn.example.com/avatar/image/usr-1/abc-200x200-fit-q80.webp"
+ */
+declare function buildImageVariantUrl(originalUrl: string, options: ImageVariantOptions): string;
+
+/**
+ * Build HLS playlist URL from an original video URL.
+ *
+ * Example:
+ *   buildVideoHlsUrl("https://cdn.example.com/gallery/video/usr-1/xyz.mp4")
+ *   → "https://cdn.example.com/gallery/video/usr-1/xyz/playlist.m3u8"
+ */
+declare function buildVideoHlsUrl(originalUrl: string): string;
+
+/**
+ * Build thumbnail URL from an original video URL.
+ *
+ * Example:
+ *   buildVideoThumbnailUrl("https://cdn.example.com/gallery/video/usr-1/xyz.mp4")
+ *   → "https://cdn.example.com/gallery/video/usr-1/xyz/thumbnail.webp"
+ */
+declare function buildVideoThumbnailUrl(originalUrl: string): string;
+
+export { IMAGE_FORMAT, IMAGE_RESIZE_TYPE, type ImageFormat, type ImageResizeType, type ImageVariantOptions, MEDIA_DEFAULTS, MEDIA_PURPOSE, MEDIA_STATUS, MEDIA_TYPE, type MediaPurpose, type MediaStatus, type MediaType, type ParsedMediaUrl, R2_PATH, buildImageVariantUrl, buildVariantString, buildVideoHlsUrl, buildVideoThumbnailUrl, parseMediaUrl };

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+declare const MEDIA_TYPE: {
+    readonly IMAGE: "image";
+    readonly VIDEO: "video";
+};
+declare const MEDIA_PURPOSE: {
+    readonly AVATAR: "avatar";
+    readonly HERO: "hero";
+    readonly GALLERY: "gallery";
+};
+declare const MEDIA_STATUS: {
+    readonly PENDING: "pending";
+    readonly UPLOADED: "uploaded";
+    readonly PROCESSING: "processing";
+    readonly READY: "ready";
+    readonly ERROR: "error";
+};
+declare const IMAGE_FORMAT: {
+    readonly WEBP: "webp";
+    readonly AVIF: "avif";
+    readonly JPEG: "jpeg";
+    readonly PNG: "png";
+    readonly JPG: "jpg";
+};
+declare const IMAGE_RESIZE_TYPE: {
+    readonly FIT: "fit";
+    readonly FILL: "fill";
+    readonly AUTO: "auto";
+};
+declare const R2_PATH: {
+    readonly HLS_PLAYLIST: "playlist.m3u8";
+    readonly THUMBNAIL: "thumbnail.webp";
+};
+declare const MEDIA_DEFAULTS: {
+    readonly IMAGE_FORMAT: "webp";
+};
+
+type MediaType = (typeof MEDIA_TYPE)[keyof typeof MEDIA_TYPE];
+type MediaPurpose = (typeof MEDIA_PURPOSE)[keyof typeof MEDIA_PURPOSE];
+type MediaStatus = (typeof MEDIA_STATUS)[keyof typeof MEDIA_STATUS];
+type ImageFormat = (typeof IMAGE_FORMAT)[keyof typeof IMAGE_FORMAT];
+type ImageResizeType = (typeof IMAGE_RESIZE_TYPE)[keyof typeof IMAGE_RESIZE_TYPE];
+interface ParsedMediaUrl {
+    /** Full original URL */
+    originalUrl: string;
+    /** CDN base including protocol and host */
+    cdnBase: string;
+    /** Object key without CDN base */
+    objectKey: string;
+    /** Purpose segment: avatar, hero, gallery */
+    purpose: MediaPurpose;
+    /** Type segment: image, video */
+    type: MediaType;
+    /** User ID segment */
+    userId: string;
+    /** File name without extension */
+    name: string;
+    /** File extension without dot */
+    extension: string;
+}
+interface ImageVariantOptions {
+    /** Target width in pixels (1-4096) */
+    width: number;
+    /** Target height in pixels (1-4096) */
+    height: number;
+    /** Resize type: fit, fill, auto */
+    resizeType: ImageResizeType;
+    /** Output format (default: webp) */
+    format?: ImageFormat;
+    /** Quality 1-100 */
+    quality?: number;
+}
+
+/**
+ * Parse a full media URL into structured components.
+ *
+ * Expected URL pattern:
+ *   {cdnBase}/{purpose}/{type}/{userId}/{name}.{extension}
+ *
+ * Example:
+ *   https://cdn.example.com/avatar/image/usr-1/abc.jpg
+ *   → { cdnBase: "https://cdn.example.com", purpose: "avatar", type: "image", userId: "usr-1", name: "abc", extension: "jpg" }
+ */
+declare function parseMediaUrl(originalUrl: string): ParsedMediaUrl;
+
+/**
+ * Build a deterministic variant string from image variant options.
+ *
+ * Format: {width}x{height}-{resizeType}[-q{quality}]
+ *
+ * Examples:
+ *   { width: 200, height: 200, resizeType: 'fit' }            → "200x200-fit"
+ *   { width: 200, height: 200, resizeType: 'fit', quality: 80 } → "200x200-fit-q80"
+ */
+declare function buildVariantString(options: ImageVariantOptions): string;
+
+/**
+ * Build a full CDN URL for an image variant.
+ *
+ * Takes an original image URL and variant options, returns the CDN URL
+ * for that specific variant.
+ *
+ * Example:
+ *   buildImageVariantUrl("https://cdn.example.com/avatar/image/usr-1/abc.jpg", {
+ *     width: 200, height: 200, resizeType: 'fit', quality: 80
+ *   })
+ *   → "https://cdn.example.com/avatar/image/usr-1/abc-200x200-fit-q80.webp"
+ */
+declare function buildImageVariantUrl(originalUrl: string, options: ImageVariantOptions): string;
+
+/**
+ * Build HLS playlist URL from an original video URL.
+ *
+ * Example:
+ *   buildVideoHlsUrl("https://cdn.example.com/gallery/video/usr-1/xyz.mp4")
+ *   → "https://cdn.example.com/gallery/video/usr-1/xyz/playlist.m3u8"
+ */
+declare function buildVideoHlsUrl(originalUrl: string): string;
+
+/**
+ * Build thumbnail URL from an original video URL.
+ *
+ * Example:
+ *   buildVideoThumbnailUrl("https://cdn.example.com/gallery/video/usr-1/xyz.mp4")
+ *   → "https://cdn.example.com/gallery/video/usr-1/xyz/thumbnail.webp"
+ */
+declare function buildVideoThumbnailUrl(originalUrl: string): string;
+
+export { IMAGE_FORMAT, IMAGE_RESIZE_TYPE, type ImageFormat, type ImageResizeType, type ImageVariantOptions, MEDIA_DEFAULTS, MEDIA_PURPOSE, MEDIA_STATUS, MEDIA_TYPE, type MediaPurpose, type MediaStatus, type MediaType, type ParsedMediaUrl, R2_PATH, buildImageVariantUrl, buildVariantString, buildVideoHlsUrl, buildVideoThumbnailUrl, parseMediaUrl };

package/dist/index.js

@@ -0,0 +1,162 @@
+// src/constants.ts
+var MEDIA_TYPE = {
+  IMAGE: "image",
+  VIDEO: "video"
+};
+var MEDIA_PURPOSE = {
+  AVATAR: "avatar",
+  HERO: "hero",
+  GALLERY: "gallery"
+};
+var MEDIA_STATUS = {
+  PENDING: "pending",
+  UPLOADED: "uploaded",
+  PROCESSING: "processing",
+  READY: "ready",
+  ERROR: "error"
+};
+var IMAGE_FORMAT = {
+  WEBP: "webp",
+  AVIF: "avif",
+  JPEG: "jpeg",
+  PNG: "png",
+  JPG: "jpg"
+};
+var IMAGE_RESIZE_TYPE = {
+  FIT: "fit",
+  FILL: "fill",
+  AUTO: "auto"
+};
+var R2_PATH = {
+  HLS_PLAYLIST: "playlist.m3u8",
+  THUMBNAIL: "thumbnail.webp"
+};
+var MEDIA_DEFAULTS = {
+  IMAGE_FORMAT: IMAGE_FORMAT.WEBP
+};
+
+// src/parse-media-url.ts
+var VALID_PURPOSES = new Set(Object.values(MEDIA_PURPOSE));
+var VALID_TYPES = new Set(Object.values(MEDIA_TYPE));
+function parseMediaUrl(originalUrl) {
+  let url;
+  try {
+    url = new URL(originalUrl);
+  } catch {
+    throw new Error(`Invalid media URL: "${originalUrl}"`);
+  }
+  const pathname = url.pathname.startsWith("/") ? url.pathname.slice(1) : url.pathname;
+  const segments = pathname.split("/");
+  if (segments.length < 4) {
+    throw new Error(
+      `Invalid media URL path: expected at least 4 segments (purpose/type/userId/filename), got ${segments.length} in "${pathname}"`
+    );
+  }
+  const [purpose, type, userId, filename] = segments;
+  if (!VALID_PURPOSES.has(purpose)) {
+    throw new Error(
+      `Invalid media purpose: "${purpose}". Expected one of: ${[...VALID_PURPOSES].join(", ")}`
+    );
+  }
+  if (!VALID_TYPES.has(type)) {
+    throw new Error(
+      `Invalid media type: "${type}". Expected one of: ${[...VALID_TYPES].join(", ")}`
+    );
+  }
+  if (!userId) {
+    throw new Error("Missing userId segment in media URL");
+  }
+  if (!filename) {
+    throw new Error("Missing filename segment in media URL");
+  }
+  const dotIndex = filename.lastIndexOf(".");
+  if (dotIndex <= 0) {
+    throw new Error(`Invalid filename: "${filename}". Expected format: "name.extension"`);
+  }
+  const name = filename.slice(0, dotIndex);
+  const extension = filename.slice(dotIndex + 1);
+  if (!extension) {
+    throw new Error(`Missing file extension in filename: "${filename}"`);
+  }
+  const cdnBase = `${url.protocol}//${url.host}`;
+  const objectKey = pathname;
+  return {
+    originalUrl,
+    cdnBase,
+    objectKey,
+    purpose,
+    type,
+    userId,
+    name,
+    extension
+  };
+}
+
+// src/build-variant-string.ts
+function buildVariantString(options) {
+  validateVariantOptions(options);
+  const parts = [`${options.width}x${options.height}`, options.resizeType];
+  if (options.quality != null) {
+    parts.push(`q${options.quality}`);
+  }
+  return parts.join("-");
+}
+function validateVariantOptions(options) {
+  if (!Number.isInteger(options.width) || options.width < 1 || options.width > 4096) {
+    throw new Error(`Invalid width: ${options.width}. Must be an integer between 1 and 4096.`);
+  }
+  if (!Number.isInteger(options.height) || options.height < 1 || options.height > 4096) {
+    throw new Error(`Invalid height: ${options.height}. Must be an integer between 1 and 4096.`);
+  }
+  if (options.quality != null) {
+    if (!Number.isInteger(options.quality) || options.quality < 1 || options.quality > 100) {
+      throw new Error(
+        `Invalid quality: ${options.quality}. Must be an integer between 1 and 100.`
+      );
+    }
+  }
+}
+
+// src/build-image-variant-url.ts
+function buildImageVariantUrl(originalUrl, options) {
+  const parsed = parseMediaUrl(originalUrl);
+  if (parsed.type !== "image") {
+    throw new Error(`Expected image URL, got type "${parsed.type}" in "${originalUrl}"`);
+  }
+  const variant = buildVariantString(options);
+  const format = options.format ?? MEDIA_DEFAULTS.IMAGE_FORMAT;
+  return `${parsed.cdnBase}/${parsed.purpose}/${parsed.type}/${parsed.userId}/${parsed.name}-${variant}.${format}`;
+}
+
+// src/build-video-hls-url.ts
+function buildVideoHlsUrl(originalUrl) {
+  const parsed = parseMediaUrl(originalUrl);
+  if (parsed.type !== "video") {
+    throw new Error(`Expected video URL, got type "${parsed.type}" in "${originalUrl}"`);
+  }
+  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.HLS_PLAYLIST}`;
+}
+
+// src/build-video-thumbnail-url.ts
+function buildVideoThumbnailUrl(originalUrl) {
+  const parsed = parseMediaUrl(originalUrl);
+  if (parsed.type !== "video") {
+    throw new Error(`Expected video URL, got type "${parsed.type}" in "${originalUrl}"`);
+  }
+  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.THUMBNAIL}`;
+}
+export {
+  IMAGE_FORMAT,
+  IMAGE_RESIZE_TYPE,
+  MEDIA_DEFAULTS,
+  MEDIA_PURPOSE,
+  MEDIA_STATUS,
+  MEDIA_TYPE,
+  R2_PATH,
+  buildImageVariantUrl,
+  buildVariantString,
+  buildVideoHlsUrl,
+  buildVideoThumbnailUrl,
+  parseMediaUrl
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/parse-media-url.ts","../src/build-variant-string.ts","../src/build-image-variant-url.ts","../src/build-video-hls-url.ts","../src/build-video-thumbnail-url.ts"],"sourcesContent":["// ============================================================================\r\n// MEDIA TYPE\r\n// ============================================================================\r\n\r\nexport const MEDIA_TYPE = {\r\n  IMAGE: 'image',\r\n  VIDEO: 'video',\r\n} as const;\r\n\r\n// ============================================================================\r\n// MEDIA PURPOSE\r\n// ============================================================================\r\n\r\nexport const MEDIA_PURPOSE = {\r\n  AVATAR: 'avatar',\r\n  HERO: 'hero',\r\n  GALLERY: 'gallery',\r\n} as const;\r\n\r\n// ============================================================================\r\n// MEDIA STATUS\r\n// ============================================================================\r\n\r\nexport const MEDIA_STATUS = {\r\n  PENDING: 'pending',\r\n  UPLOADED: 'uploaded',\r\n  PROCESSING: 'processing',\r\n  READY: 'ready',\r\n  ERROR: 'error',\r\n} as const;\r\n\r\n// ============================================================================\r\n// IMAGE FORMAT\r\n// ============================================================================\r\n\r\nexport const IMAGE_FORMAT = {\r\n  WEBP: 'webp',\r\n  AVIF: 'avif',\r\n  JPEG: 'jpeg',\r\n  PNG: 'png',\r\n  JPG: 'jpg',\r\n} as const;\r\n\r\n// ============================================================================\r\n// IMAGE RESIZE TYPE\r\n// ============================================================================\r\n\r\nexport const IMAGE_RESIZE_TYPE = {\r\n  FIT: 'fit',\r\n  FILL: 'fill',\r\n  AUTO: 'auto',\r\n} as const;\r\n\r\n// ============================================================================\r\n// R2/CDN PATH CONSTANTS\r\n// ============================================================================\r\n\r\nexport const R2_PATH = {\r\n  HLS_PLAYLIST: 'playlist.m3u8',\r\n  THUMBNAIL: 'thumbnail.webp',\r\n} as const;\r\n\r\n// ============================================================================\r\n// DEFAULTS\r\n// ============================================================================\r\n\r\nexport const MEDIA_DEFAULTS = {\r\n  IMAGE_FORMAT: IMAGE_FORMAT.WEBP,\r\n} as const;\r\n","import { MEDIA_PURPOSE, MEDIA_TYPE } from './constants';\r\nimport type { ParsedMediaUrl, MediaPurpose, MediaType } from './types';\r\n\r\nconst VALID_PURPOSES = new Set<string>(Object.values(MEDIA_PURPOSE));\r\nconst VALID_TYPES = new Set<string>(Object.values(MEDIA_TYPE));\r\n\r\n/**\r\n * Parse a full media URL into structured components.\r\n *\r\n * Expected URL pattern:\r\n *   {cdnBase}/{purpose}/{type}/{userId}/{name}.{extension}\r\n *\r\n * Example:\r\n *   https://cdn.example.com/avatar/image/usr-1/abc.jpg\r\n *   → { cdnBase: \"https://cdn.example.com\", purpose: \"avatar\", type: \"image\", userId: \"usr-1\", name: \"abc\", extension: \"jpg\" }\r\n */\r\nexport function parseMediaUrl(originalUrl: string): ParsedMediaUrl {\r\n  let url: URL;\r\n  try {\r\n    url = new URL(originalUrl);\r\n  } catch {\r\n    throw new Error(`Invalid media URL: \"${originalUrl}\"`);\r\n  }\r\n\r\n  // Remove leading slash and split into segments\r\n  const pathname = url.pathname.startsWith('/') ? url.pathname.slice(1) : url.pathname;\r\n  const segments = pathname.split('/');\r\n\r\n  if (segments.length < 4) {\r\n    throw new Error(\r\n      `Invalid media URL path: expected at least 4 segments (purpose/type/userId/filename), got ${segments.length} in \"${pathname}\"`,\r\n    );\r\n  }\r\n\r\n  const [purpose, type, userId, filename] = segments as [string, string, string, string];\r\n\r\n  if (!VALID_PURPOSES.has(purpose)) {\r\n    throw new Error(\r\n      `Invalid media purpose: \"${purpose}\". Expected one of: ${[...VALID_PURPOSES].join(', ')}`,\r\n    );\r\n  }\r\n\r\n  if (!VALID_TYPES.has(type)) {\r\n    throw new Error(\r\n      `Invalid media type: \"${type}\". Expected one of: ${[...VALID_TYPES].join(', ')}`,\r\n    );\r\n  }\r\n\r\n  if (!userId) {\r\n    throw new Error('Missing userId segment in media URL');\r\n  }\r\n\r\n  if (!filename) {\r\n    throw new Error('Missing filename segment in media URL');\r\n  }\r\n\r\n  const dotIndex = filename.lastIndexOf('.');\r\n  if (dotIndex <= 0) {\r\n    throw new Error(`Invalid filename: \"${filename}\". Expected format: \"name.extension\"`);\r\n  }\r\n\r\n  const name = filename.slice(0, dotIndex);\r\n  const extension = filename.slice(dotIndex + 1);\r\n\r\n  if (!extension) {\r\n    throw new Error(`Missing file extension in filename: \"${filename}\"`);\r\n  }\r\n\r\n  const cdnBase = `${url.protocol}//${url.host}`;\r\n  const objectKey = pathname;\r\n\r\n  return {\r\n    originalUrl,\r\n    cdnBase,\r\n    objectKey,\r\n    purpose: purpose as MediaPurpose,\r\n    type: type as MediaType,\r\n    userId,\r\n    name,\r\n    extension,\r\n  };\r\n}\r\n","import type { ImageVariantOptions } from './types';\r\n\r\n/**\r\n * Build a deterministic variant string from image variant options.\r\n *\r\n * Format: {width}x{height}-{resizeType}[-q{quality}]\r\n *\r\n * Examples:\r\n *   { width: 200, height: 200, resizeType: 'fit' }            → \"200x200-fit\"\r\n *   { width: 200, height: 200, resizeType: 'fit', quality: 80 } → \"200x200-fit-q80\"\r\n */\r\nexport function buildVariantString(options: ImageVariantOptions): string {\r\n  validateVariantOptions(options);\r\n\r\n  const parts: string[] = [`${options.width}x${options.height}`, options.resizeType];\r\n\r\n  if (options.quality != null) {\r\n    parts.push(`q${options.quality}`);\r\n  }\r\n\r\n  return parts.join('-');\r\n}\r\n\r\nfunction validateVariantOptions(options: ImageVariantOptions): void {\r\n  if (!Number.isInteger(options.width) || options.width < 1 || options.width > 4096) {\r\n    throw new Error(`Invalid width: ${options.width}. Must be an integer between 1 and 4096.`);\r\n  }\r\n\r\n  if (!Number.isInteger(options.height) || options.height < 1 || options.height > 4096) {\r\n    throw new Error(`Invalid height: ${options.height}. Must be an integer between 1 and 4096.`);\r\n  }\r\n\r\n  if (options.quality != null) {\r\n    if (!Number.isInteger(options.quality) || options.quality < 1 || options.quality > 100) {\r\n      throw new Error(\r\n        `Invalid quality: ${options.quality}. Must be an integer between 1 and 100.`,\r\n      );\r\n    }\r\n  }\r\n}\r\n","import { MEDIA_DEFAULTS } from './constants';\r\nimport { parseMediaUrl } from './parse-media-url';\r\nimport { buildVariantString } from './build-variant-string';\r\nimport type { ImageVariantOptions } from './types';\r\n\r\n/**\r\n * Build a full CDN URL for an image variant.\r\n *\r\n * Takes an original image URL and variant options, returns the CDN URL\r\n * for that specific variant.\r\n *\r\n * Example:\r\n *   buildImageVariantUrl(\"https://cdn.example.com/avatar/image/usr-1/abc.jpg\", {\r\n *     width: 200, height: 200, resizeType: 'fit', quality: 80\r\n *   })\r\n *   → \"https://cdn.example.com/avatar/image/usr-1/abc-200x200-fit-q80.webp\"\r\n */\r\nexport function buildImageVariantUrl(originalUrl: string, options: ImageVariantOptions): string {\r\n  const parsed = parseMediaUrl(originalUrl);\r\n\r\n  if (parsed.type !== 'image') {\r\n    throw new Error(`Expected image URL, got type \"${parsed.type}\" in \"${originalUrl}\"`);\r\n  }\r\n\r\n  const variant = buildVariantString(options);\r\n  const format = options.format ?? MEDIA_DEFAULTS.IMAGE_FORMAT;\r\n\r\n  return `${parsed.cdnBase}/${parsed.purpose}/${parsed.type}/${parsed.userId}/${parsed.name}-${variant}.${format}`;\r\n}\r\n","import { R2_PATH } from './constants';\r\nimport { parseMediaUrl } from './parse-media-url';\r\n\r\n/**\r\n * Build HLS playlist URL from an original video URL.\r\n *\r\n * Example:\r\n *   buildVideoHlsUrl(\"https://cdn.example.com/gallery/video/usr-1/xyz.mp4\")\r\n *   → \"https://cdn.example.com/gallery/video/usr-1/xyz/playlist.m3u8\"\r\n */\r\nexport function buildVideoHlsUrl(originalUrl: string): string {\r\n  const parsed = parseMediaUrl(originalUrl);\r\n\r\n  if (parsed.type !== 'video') {\r\n    throw new Error(`Expected video URL, got type \"${parsed.type}\" in \"${originalUrl}\"`);\r\n  }\r\n\r\n  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.HLS_PLAYLIST}`;\r\n}\r\n","import { R2_PATH } from './constants';\r\nimport { parseMediaUrl } from './parse-media-url';\r\n\r\n/**\r\n * Build thumbnail URL from an original video URL.\r\n *\r\n * Example:\r\n *   buildVideoThumbnailUrl(\"https://cdn.example.com/gallery/video/usr-1/xyz.mp4\")\r\n *   → \"https://cdn.example.com/gallery/video/usr-1/xyz/thumbnail.webp\"\r\n */\r\nexport function buildVideoThumbnailUrl(originalUrl: string): string {\r\n  const parsed = parseMediaUrl(originalUrl);\r\n\r\n  if (parsed.type !== 'video') {\r\n    throw new Error(`Expected video URL, got type \"${parsed.type}\" in \"${originalUrl}\"`);\r\n  }\r\n\r\n  return `${parsed.cdnBase}/${parsed.purpose}/video/${parsed.userId}/${parsed.name}/${R2_PATH.THUMBNAIL}`;\r\n}\r\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sproux/media-sdk",
+  "version": "0.1.0",
+  "description": "Media URL builder library for Sproux — build image variant URLs, video HLS playlist URLs, and thumbnails from original media URLs.",
+  "author": "Sproux",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "media",
+    "cdn",
+    "image",
+    "video",
+    "url-builder",
+    "hls",
+    "sproux"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beincom/image-proxy-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/beincom/image-proxy-sdk/issues"
+  },
+  "homepage": "https://github.com/beincom/image-proxy-sdk#readme"
+}