@verisure-italy/media-library-types

Shared runtime and TypeScript contracts for the Verisure Italy Media Library.

Scope

The package owns:

• media statuses, context tags, generated formats, and resize fit modes;
• the canonical variant preset catalog;
• processing options accepted by the public API;
• media item and variant response schemas;
• upload, create, replace, update, and list request schemas.

The package does not own AWS configuration, DynamoDB keys, SQS processing jobs, CDN URL construction, or generic srcSet generation.

Install

npm install @verisure-italy/media-library-types zod

Preset catalog

mediaVariantPresetCatalog is the only canonical source for preset targets. Catalog width and height describe processing targets. MediaVariant.width and MediaVariant.height describe actual generated output and must be used by consumers when rendering images.

import {
  mediaVariantPresetCatalog,
  mediaVariantPresetNameSchema,
  type MediaVariantPresetName,
} from '@verisure-italy/media-library-types'

const preset: MediaVariantPresetName = mediaVariantPresetNameSchema.parse('funnel-hero-desktop')
const target = mediaVariantPresetCatalog[preset]

Approved divergent targets:

| Preset | Target | Fit | | -------------------------- | ----------- | -------- | | xlarge | 1800px wide | inside | | funnel-costs-desktop | 1480 x 900 | cover | | funnel-content-landscape | 700 x 700 | cover |

Key strengths uses one canonical funnel-key-strengths-image preset at 600px wide. Responsive consumers may reference different media IDs with the same preset when needed.

Before adopting strict response validation, services must stop generating the obsolete funnel-key-strengths-desktop and funnel-key-strengths-mobile variants and reprocess or replace records that still contain them.

Media URLs

MediaVariant.url is the authoritative resolved URL. Consumers must preserve it exactly and must not rebuild it from mediaId, preset, or s3Key. MediaVariant.s3Key remains part of the API response but is opaque to consumers.

import { mediaVariantSchema } from '@verisure-italy/media-library-types'

const variant = mediaVariantSchema.parse(apiResponse)
renderImage(variant.url, variant.width, variant.height)

Request parsing

Request types use Zod input types so defaulted fields remain optional for API clients. Services can use parsed output aliases when they need defaults applied.

import {
  createMediaRequestSchema,
  type CreateMediaRequest,
  type ParsedCreateMediaRequest,
} from '@verisure-italy/media-library-types'

const request: CreateMediaRequest = {
  project: 'sls-lp',
  originalFilename: 'hero.png',
  originalObjectKey: 'media/sls-lp/uploads/id/original/hero.png',
  mimeType: 'image/png',
}

const parsed: ParsedCreateMediaRequest = createMediaRequestSchema.parse(request)

Export inventory

• mediaStatusSchema, contextTagSchema, generatedFormatSchema, fitModeSchema
• mediaVariantPresetNameSchema, mediaVariantPresetDefinitionSchema
• mediaVariantPresetCatalog, mediaVariantPresetNames, mediaVariantPresetDefinitions
• processingOptionsSchema
• mediaVariantSchema, processingErrorSchema, mediaItemSchema
• mediaListResponseSchema
• presignUploadRequestSchema, presignUploadResponseSchema
• replacementPresignUploadRequestSchema, replacementPresignUploadResponseSchema
• createMediaRequestSchema, replaceMediaRequestSchema
• updateMediaMetadataRequestSchema, mediaListQuerySchema