@ossy/media-tasks 3.18.0 → 3.19.0

package/src/convert-common-audio.task.js

@@ -0,0 +1,142 @@
+import { createLogger } from '@ossy/observability'
+import { StorageClient } from '@ossy/platform'
+import { originalObjectKey, taskArtifactObjectKey } from '@ossy/platform/storage-keys'
+import { GetResource, placeTaskArtifacts } from '@ossy/resources'
+import {
+  contentTypeForCommonAudioFormat,
+  convertCommonAudioBuffer,
+  isAlreadyCommonAudioTargetFormat,
+  isAudioContentType,
+  normalizeCommonAudioFormat,
+  normalizeCommonAudioQuality,
+} from './convert-common-audio.js'
+import { loadSourceBuffer } from './load-source-buffer.js'
+import { resolveConfiguredPlacements } from './resolve-configured-placement.js'
+
+const log = createLogger('media-tasks')
+
+const TASK_ID = '@ossy/media-tasks/tasks/convert-common-audio'
+const SCHEMA_ID = '@ossy/media-tasks/schema/convert-common-audio'
+const CONCEPT = 'convert-common-audio'
+const AUDIO_ARTIFACT = 'audio'
+const OUTPUT = {
+  name: 'converted',
+  kind: 'location',
+  schemaId: SCHEMA_ID,
+  contentType: 'application/json',
+}
+
+export const metadata = {
+  id: TASK_ID,
+  triggers: [
+    {
+      type: '@ossy/platform/schema/file',
+      event: 'Created',
+      match: { 'content.ContentType': 'audio/*' },
+    },
+    {
+      kind: 'on_action',
+      action: '@ossy/media-tasks/actions/convert-common-audio',
+    },
+  ],
+  outputs: [OUTPUT],
+  inputs: [
+    {
+      name: 'format',
+      type: 'text',
+      default: 'mp3',
+      sources: ['payload', 'config'],
+      options: ['mp3', 'aac', 'ogg', 'wav', 'aiff', 'flac'],
+      description: 'Target format: mp3 (default), aac, ogg, wav, aiff, or flac',
+    },
+    {
+      name: 'quality',
+      type: 'number',
+      default: 85,
+      sources: ['payload', 'config'],
+      description: 'Encode quality 1–100 for lossy formats (mp3/aac/ogg); ignored for lossless (wav/aiff/flac)',
+    },
+  ],
+  configurable: true,
+}
+
+export async function run ({ event, payload, sdk, inputs }) {
+  const resourceId = event?.resourceId || payload?.resourceId
+  if (!resourceId) {
+    throw new Error('[media-tasks/tasks/convert-common-audio] resourceId is required')
+  }
+
+  const format = normalizeCommonAudioFormat(inputs?.format)
+  const quality = normalizeCommonAudioQuality(inputs?.quality)
+
+  log.info(`[media-tasks/tasks/convert-common-audio] starting for resource ${resourceId} → ${format}`)
+
+  const resource = await sdk.invoke(GetResource, { resourceId })
+  // content.Key is stripped by the API media layer; derive from resource id.
+  const key = originalObjectKey(resource.id)
+
+  const sourceContentType = resource?.content?.ContentType || 'application/octet-stream'
+
+  if (!isAudioContentType(sourceContentType)) {
+    throw new Error(
+      `[media-tasks/tasks/convert-common-audio] unsupported ContentType ${sourceContentType} for ${resourceId}`,
+    )
+  }
+
+  if (isAlreadyCommonAudioTargetFormat(sourceContentType, format)) {
+    log.info(
+      `[media-tasks/tasks/convert-common-audio] skip ${resourceId}: already ${contentTypeForCommonAudioFormat(format)}`,
+    )
+    return { skipped: true, reason: 'already-target-format', format, sourceContentType }
+  }
+
+  const sourceBuffer = await loadSourceBuffer(key)
+  if (!sourceBuffer) {
+    throw new Error(`[media-tasks/tasks/convert-common-audio] missing file bytes for ${resourceId}`)
+  }
+
+  const converted = await convertCommonAudioBuffer(sourceBuffer, { format, quality })
+  const audioKey = taskArtifactObjectKey(resourceId, CONCEPT, AUDIO_ARTIFACT)
+  await StorageClient.save(audioKey, converted.buffer)
+  log.info(`[media-tasks/tasks/convert-common-audio] saved audio ${audioKey} (${converted.size} bytes)`)
+
+  const body = {
+    format: converted.format,
+    contentType: converted.contentType,
+    sourceContentType,
+    quality,
+    size: converted.size,
+    audioKey,
+  }
+
+  const metaKey = taskArtifactObjectKey(resourceId, CONCEPT, OUTPUT.name)
+  await StorageClient.save(metaKey, Buffer.from(JSON.stringify(body), 'utf8'))
+  log.info(`[media-tasks/tasks/convert-common-audio] saved ${metaKey}`)
+
+  const placementLocations = await resolveConfiguredPlacements(sdk, TASK_ID, OUTPUT.name)
+  const placed = await placeTaskArtifacts({
+    sdk,
+    sourceResource: resource,
+    taskId: TASK_ID,
+    output: OUTPUT,
+    body,
+    artifactKey: metaKey,
+    placementLocations,
+  })
+  if (placed.length) {
+    log.info(`[media-tasks/tasks/convert-common-audio] placed ${placed.length} resource(s)`)
+  } else {
+    log.info('[media-tasks/tasks/convert-common-audio] artifact only (no placement location configured)')
+  }
+
+  return {
+    output: OUTPUT.name,
+    key: metaKey,
+    audioKey,
+    format: converted.format,
+    contentType: converted.contentType,
+    quality,
+    placedResourceIds: placed.map((r) => r.id),
+    placedResourceId: placed[0]?.id ?? null,
+  }
+}

package/src/convert-common-image.action.js

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: '@ossy/media-tasks/actions/convert-common-image',
+  access: 'workspace',
+  label: 'automation.task.convert-common-image.title',
+}

package/src/convert-common-image.js

@@ -0,0 +1,143 @@
+/**
+ * First-slice image format converter (#896).
+ *
+ * Scope: convert camera-phone / awkward uploads (HEIC/HEIF, TIFF, BMP, AVIF)
+ * and the configured target formats themselves (JPEG/PNG/WebP → another target,
+ * e.g. JPEG→WebP) via sharp. Already-at-target sources are skipped.
+ * Manual invoke still accepts any image/*. Document conversions (DOCX→PDF, etc.)
+ * are out of scope — they need a different engine.
+ */
+
+/** @type {ReadonlyArray<string>} */
+export const CONVERT_SOURCE_MIME_TYPES = Object.freeze([
+  'image/heic',
+  'image/heif',
+  'image/tiff',
+  'image/tif',
+  'image/bmp',
+  'image/x-ms-bmp',
+  'image/x-bmp',
+  'image/avif',
+  // Target formats are also valid inputs so folder-watch can convert e.g. JPEG→WebP.
+  'image/jpeg',
+  'image/jpg',
+  'image/pjpeg',
+  'image/png',
+  'image/webp',
+])
+
+/** @type {ReadonlyArray<string>} */
+export const CONVERT_TARGET_FORMATS = Object.freeze(['jpeg', 'png', 'webp'])
+
+/** @type {Readonly<Record<string, string>>} */
+export const CONVERT_FORMAT_CONTENT_TYPES = Object.freeze({
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  webp: 'image/webp',
+})
+
+const DEFAULT_FORMAT = 'jpeg'
+const DEFAULT_QUALITY = 85
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeConvertFormat (value) {
+  const raw = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  if (raw === 'jpg') return 'jpeg'
+  if (CONVERT_TARGET_FORMATS.includes(raw)) return raw
+  return DEFAULT_FORMAT
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function normalizeConvertQuality (value) {
+  const n = typeof value === 'number' ? value : Number(String(value ?? '').trim())
+  if (!Number.isFinite(n)) return DEFAULT_QUALITY
+  return Math.min(100, Math.max(1, Math.round(n)))
+}
+
+/**
+ * @param {unknown} contentType
+ * @returns {string}
+ */
+export function normalizeContentType (contentType) {
+  return String(contentType || '')
+    .split(';')[0]
+    .trim()
+    .toLowerCase()
+}
+
+/**
+ * True when upload MIME is in the automatic conversion set.
+ *
+ * @param {unknown} contentType
+ * @returns {boolean}
+ */
+export function isConvertSourceMime (contentType) {
+  return CONVERT_SOURCE_MIME_TYPES.includes(normalizeContentType(contentType))
+}
+
+/**
+ * @param {string} format
+ * @returns {string}
+ */
+export function contentTypeForFormat (format) {
+  const normalized = normalizeConvertFormat(format)
+  return CONVERT_FORMAT_CONTENT_TYPES[normalized] || CONVERT_FORMAT_CONTENT_TYPES.jpeg
+}
+
+/**
+ * Skip when the source is already the requested MIME (no-op conversion).
+ *
+ * @param {unknown} sourceContentType
+ * @param {string} targetFormat
+ * @returns {boolean}
+ */
+export function isAlreadyTargetFormat (sourceContentType, targetFormat) {
+  return normalizeContentType(sourceContentType) === contentTypeForFormat(targetFormat)
+}
+
+/**
+ * Convert an image buffer to the target format via sharp.
+ *
+ * @param {import('sharp')} sharp
+ * @param {Buffer} sourceBuffer
+ * @param {{ format?: string, quality?: number }} [options]
+ * @returns {Promise<{
+ *   buffer: Buffer,
+ *   format: string,
+ *   contentType: string,
+ *   width?: number,
+ *   height?: number,
+ *   size: number,
+ * }>}
+ */
+export async function convertImageBuffer (sharp, sourceBuffer, options = {}) {
+  const format = normalizeConvertFormat(options.format)
+  const quality = normalizeConvertQuality(options.quality)
+
+  let pipeline = sharp(sourceBuffer, { failOn: 'none' }).rotate()
+  if (format === 'jpeg') {
+    // Flatten transparency onto white — JPEG has no alpha.
+    pipeline = pipeline.flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality, mozjpeg: true })
+  } else if (format === 'png') {
+    pipeline = pipeline.png({ compressionLevel: 9 })
+  } else if (format === 'webp') {
+    pipeline = pipeline.webp({ quality })
+  }
+
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true })
+  return {
+    buffer: data,
+    format,
+    contentType: contentTypeForFormat(format),
+    ...(info.width != null ? { width: info.width } : {}),
+    ...(info.height != null ? { height: info.height } : {}),
+    size: data.length,
+  }
+}

package/src/convert-common-image.schema.js

@@ -0,0 +1,46 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
+export default {
+  name: 'Convert common image',
+  id: '@ossy/media-tasks/schema/convert-common-image',
+  categoryName: 'Media processing',
+  icon: 'swap',
+  fields: [
+    {
+      name: 'format',
+      type: 'text',
+      description: 'Output format (jpeg, png, or webp)',
+    },
+    {
+      name: 'contentType',
+      type: 'text',
+      description: 'MIME type of the converted image bytes',
+    },
+    {
+      name: 'sourceContentType',
+      type: 'text',
+      description: 'MIME type of the source upload',
+    },
+    {
+      name: 'width',
+      type: 'number',
+      description: 'Converted image width in pixels',
+    },
+    {
+      name: 'height',
+      type: 'number',
+      description: 'Converted image height in pixels',
+    },
+    {
+      name: 'size',
+      type: 'number',
+      description: 'Converted image byte length',
+    },
+    {
+      name: 'imageKey',
+      type: 'text',
+      description: 'Storage key for the converted image binary artifact',
+    },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
+  ],
+}

package/src/convert-common-image.spec.js

@@ -0,0 +1,101 @@
+import sharp from 'sharp'
+import {
+  CONVERT_SOURCE_MIME_TYPES,
+  contentTypeForFormat,
+  convertImageBuffer,
+  isAlreadyTargetFormat,
+  isConvertSourceMime,
+  normalizeConvertFormat,
+  normalizeConvertQuality,
+} from './convert-common-image.js'
+
+describe('convert-common-image helpers', () => {
+  it('normalizes format and quality', () => {
+    expect(normalizeConvertFormat('JPG')).toBe('jpeg')
+    expect(normalizeConvertFormat('webp')).toBe('webp')
+    expect(normalizeConvertFormat('nope')).toBe('jpeg')
+    expect(normalizeConvertQuality(72.4)).toBe(72)
+    expect(normalizeConvertQuality(0)).toBe(1)
+    expect(normalizeConvertQuality(200)).toBe(100)
+    expect(normalizeConvertQuality('bad')).toBe(85)
+  })
+
+  it('recognizes scoped upload MIME types including target formats as inputs', () => {
+    expect(isConvertSourceMime('image/heic')).toBe(true)
+    expect(isConvertSourceMime('image/tiff; charset=binary')).toBe(true)
+    expect(isConvertSourceMime('image/jpeg')).toBe(true)
+    expect(isConvertSourceMime('image/png')).toBe(true)
+    expect(isConvertSourceMime('image/webp')).toBe(true)
+    expect(isConvertSourceMime('image/gif')).toBe(false)
+    expect(CONVERT_SOURCE_MIME_TYPES).toContain('image/avif')
+  })
+
+  it('detects already-converted sources', () => {
+    expect(isAlreadyTargetFormat('image/jpeg', 'jpeg')).toBe(true)
+    expect(isAlreadyTargetFormat('image/jpeg', 'webp')).toBe(false)
+    expect(isAlreadyTargetFormat('image/png', 'jpeg')).toBe(false)
+    expect(contentTypeForFormat('webp')).toBe('image/webp')
+  })
+})
+
+describe('convertImageBuffer', () => {
+  it('converts PNG bytes to JPEG', async () => {
+    const sourceBuffer = await sharp({
+      create: {
+        width: 12,
+        height: 8,
+        channels: 3,
+        background: { r: 10, g: 20, b: 30 },
+      },
+    })
+      .png()
+      .toBuffer()
+
+    const result = await convertImageBuffer(sharp, sourceBuffer, { format: 'jpeg', quality: 80 })
+    expect(result.format).toBe('jpeg')
+    expect(result.contentType).toBe('image/jpeg')
+    expect(result.width).toBe(12)
+    expect(result.height).toBe(8)
+    expect(result.size).toBeGreaterThan(0)
+
+    const meta = await sharp(result.buffer).metadata()
+    expect(meta.format).toBe('jpeg')
+  })
+
+  it('converts to webp when requested', async () => {
+    const sourceBuffer = await sharp({
+      create: {
+        width: 8,
+        height: 8,
+        channels: 3,
+        background: { r: 200, g: 100, b: 50 },
+      },
+    })
+      .png()
+      .toBuffer()
+
+    const result = await convertImageBuffer(sharp, sourceBuffer, { format: 'webp' })
+    expect(result.contentType).toBe('image/webp')
+    const meta = await sharp(result.buffer).metadata()
+    expect(meta.format).toBe('webp')
+  })
+
+  it('converts JPEG bytes to WebP (target formats are valid inputs)', async () => {
+    const sourceBuffer = await sharp({
+      create: {
+        width: 10,
+        height: 6,
+        channels: 3,
+        background: { r: 40, g: 80, b: 120 },
+      },
+    })
+      .jpeg({ quality: 90 })
+      .toBuffer()
+
+    const result = await convertImageBuffer(sharp, sourceBuffer, { format: 'webp', quality: 80 })
+    expect(result.format).toBe('webp')
+    expect(result.contentType).toBe('image/webp')
+    const meta = await sharp(result.buffer).metadata()
+    expect(meta.format).toBe('webp')
+  })
+})

package/src/convert-common-image.task.js

@@ -0,0 +1,155 @@
+import { createLogger } from '@ossy/observability'
+import { StorageClient } from '@ossy/platform'
+import { originalObjectKey, taskArtifactObjectKey } from '@ossy/platform/storage-keys'
+import { GetResource, placeTaskArtifacts } from '@ossy/resources'
+import {
+  contentTypeForFormat,
+  convertImageBuffer,
+  isAlreadyTargetFormat,
+  isConvertSourceMime,
+  normalizeConvertFormat,
+  normalizeConvertQuality,
+} from './convert-common-image.js'
+import { loadSourceBuffer } from './load-source-buffer.js'
+import { resolveConfiguredPlacements } from './resolve-configured-placement.js'
+
+const log = createLogger('media-tasks')
+
+const TASK_ID = '@ossy/media-tasks/tasks/convert-common-image'
+const SCHEMA_ID = '@ossy/media-tasks/schema/convert-common-image'
+const CONCEPT = 'convert-common-image'
+const IMAGE_ARTIFACT = 'image'
+const OUTPUT = {
+  name: 'converted',
+  kind: 'location',
+  schemaId: SCHEMA_ID,
+  contentType: 'application/json',
+}
+
+export const metadata = {
+  id: TASK_ID,
+  triggers: [
+    // Ceiling is all images so Storage → Tasks can offer manual convert.
+    // Upload auto-run covers CONVERT_SOURCE_MIME_TYPES (awkward formats + jpeg/png/webp).
+    {
+      type: '@ossy/platform/schema/file',
+      event: 'Created',
+      match: { 'content.ContentType': 'image/*' },
+    },
+    {
+      kind: 'on_action',
+      action: '@ossy/media-tasks/actions/convert-common-image',
+    },
+  ],
+  outputs: [OUTPUT],
+  inputs: [
+    {
+      name: 'format',
+      type: 'text',
+      default: 'jpeg',
+      sources: ['payload', 'config'],
+      options: ['jpeg', 'png', 'webp'],
+      description: 'Target format: jpeg, png, or webp (default jpeg)',
+    },
+    {
+      name: 'quality',
+      type: 'number',
+      default: 85,
+      sources: ['payload', 'config'],
+      description: 'Encode quality 1–100 for jpeg/webp (ignored for png)',
+    },
+  ],
+  configurable: true,
+}
+
+export async function run ({ event, payload, sdk, inputs }) {
+  const { default: sharp } = await import('sharp')
+  const resourceId = event?.resourceId || payload?.resourceId
+  if (!resourceId) {
+    throw new Error('[media-tasks/tasks/convert-common-image] resourceId is required')
+  }
+
+  const format = normalizeConvertFormat(inputs?.format)
+  const quality = normalizeConvertQuality(inputs?.quality)
+
+  log.info(`[media-tasks/tasks/convert-common-image] starting for resource ${resourceId} → ${format}`)
+
+  const resource = await sdk.invoke(GetResource, { resourceId })
+  // content.Key is stripped by the API media layer (replaced with src URL);
+  // derive the storage key deterministically from the resource ID instead.
+  const key = originalObjectKey(resource.id)
+
+  const sourceContentType = resource?.content?.ContentType || 'application/octet-stream'
+  const triggeredByUpload = Boolean(event?.resourceId && !payload?.resourceId)
+
+  // Upload path only auto-converts the scoped MIME set; manual invoke accepts any image.
+  if (triggeredByUpload && !isConvertSourceMime(sourceContentType)) {
+    log.info(
+      `[media-tasks/tasks/convert-common-image] skip ${resourceId}: ContentType ${sourceContentType} not in convert set`,
+    )
+    return { skipped: true, reason: 'unsupported-source-mime', sourceContentType }
+  }
+
+  if (!String(sourceContentType).toLowerCase().startsWith('image/')) {
+    throw new Error(
+      `[media-tasks/tasks/convert-common-image] unsupported ContentType ${sourceContentType} for ${resourceId}`,
+    )
+  }
+
+  if (isAlreadyTargetFormat(sourceContentType, format)) {
+    log.info(
+      `[media-tasks/tasks/convert-common-image] skip ${resourceId}: already ${contentTypeForFormat(format)}`,
+    )
+    return { skipped: true, reason: 'already-target-format', format, sourceContentType }
+  }
+
+  const sourceBuffer = await loadSourceBuffer(key)
+  if (!sourceBuffer) {
+    throw new Error(`[media-tasks/tasks/convert-common-image] missing file bytes for ${resourceId}`)
+  }
+
+  const converted = await convertImageBuffer(sharp, sourceBuffer, { format, quality })
+  const imageKey = taskArtifactObjectKey(resourceId, CONCEPT, IMAGE_ARTIFACT)
+  await StorageClient.save(imageKey, converted.buffer)
+  log.info(`[media-tasks/tasks/convert-common-image] saved image ${imageKey} (${converted.size} bytes)`)
+
+  const body = {
+    format: converted.format,
+    contentType: converted.contentType,
+    sourceContentType,
+    ...(converted.width != null ? { width: converted.width } : {}),
+    ...(converted.height != null ? { height: converted.height } : {}),
+    size: converted.size,
+    imageKey,
+  }
+
+  const metaKey = taskArtifactObjectKey(resourceId, CONCEPT, OUTPUT.name)
+  await StorageClient.save(metaKey, Buffer.from(JSON.stringify(body), 'utf8'))
+  log.info(`[media-tasks/tasks/convert-common-image] saved ${metaKey}`)
+
+  const placementLocations = await resolveConfiguredPlacements(sdk, TASK_ID, OUTPUT.name)
+  const placed = await placeTaskArtifacts({
+    sdk,
+    sourceResource: resource,
+    taskId: TASK_ID,
+    output: OUTPUT,
+    body,
+    artifactKey: metaKey,
+    placementLocations,
+  })
+  if (placed.length) {
+    log.info(`[media-tasks/tasks/convert-common-image] placed ${placed.length} resource(s)`)
+  } else {
+    log.info('[media-tasks/tasks/convert-common-image] artifact only (no placement location configured)')
+  }
+
+  return {
+    output: OUTPUT.name,
+    key: metaKey,
+    imageKey,
+    format: converted.format,
+    contentType: converted.contentType,
+    placedResourceIds: placed.map((r) => r.id),
+    placedResourceId: placed[0]?.id ?? null,
+  }
+}

package/src/embed-resource.action.js

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: '@ossy/media-tasks/actions/embed-resource',
+  access: 'workspace',
+  label: 'automation.task.embed-resource.title',
+}