immich/server/src/dtos/asset-response.dto.ts

import { Selectable, ShallowDehydrateObject } from 'kysely';
import { createZodDto } from 'nestjs-zod';
import { AssetFace, AssetFile, Exif, Stack, Tag, User } from 'src/database';
import { HistoryBuilder } from 'src/decorators';
import { AuthDto } from 'src/dtos/auth.dto';
import { AssetEditActionItem } from 'src/dtos/editing.dto';
import { ExifResponseSchema, mapExif } from 'src/dtos/exif.dto';
import {
  AssetFaceWithoutPersonResponseSchema,
  PersonWithFacesResponseDto,
  PersonWithFacesResponseSchema,
  mapFacesWithoutPerson,
  mapPerson,
} from 'src/dtos/person.dto';
import { TagResponseSchema, mapTag } from 'src/dtos/tag.dto';
import { UserResponseSchema, mapUser } from 'src/dtos/user.dto';
import {
  AssetStatus,
  AssetType,
  AssetTypeSchema,
  AssetVisibility,
  AssetVisibilitySchema,
  ChecksumAlgorithm,
} from 'src/enum';
import { ImageDimensions, MaybeDehydrated } from 'src/types';
import { getDimensions } from 'src/utils/asset.util';
import { hexOrBufferToBase64 } from 'src/utils/bytes';
import { mimeTypes } from 'src/utils/mime-types';
import { isoDatetimeToDate } from 'src/validation';
import z from 'zod';

const SanitizedAssetResponseSchema = z
  .object({
    id: z.string().describe('Asset ID'),
    type: AssetTypeSchema,
    thumbhash: z
      .string()
      .describe(
        'Thumbhash for thumbnail generation (base64) also used as the c query param for thumbnail cache busting.',
      )
      .nullable(),
    originalMimeType: z.string().optional().describe('Original MIME type'),
    localDateTime: isoDatetimeToDate.describe(
      'The local date and time when the photo/video was taken, derived from EXIF metadata. This represents the photographer\'s local time regardless of timezone, stored as a timezone-agnostic timestamp. Used for timeline grouping by "local" days and months.',
    ),
    duration: z.string().nullable().describe('Video/gif duration in hh:mm:ss.SSS format (null for static images)'),
    livePhotoVideoId: z.string().nullish().describe('Live photo video ID'),
    hasMetadata: z.boolean().describe('Whether asset has metadata'),
    width: z.number().min(0).nullable().describe('Asset width'),
    height: z.number().min(0).nullable().describe('Asset height'),
  })
  .meta({ id: 'SanitizedAssetResponseDto' });

export class SanitizedAssetResponseDto extends createZodDto(SanitizedAssetResponseSchema, { codec: true }) {}

const AssetStackResponseSchema = z
  .object({
    id: z.string().describe('Stack ID'),
    primaryAssetId: z.string().describe('Primary asset ID'),
    assetCount: z.int().min(0).describe('Number of assets in stack'),
  })
  .meta({ id: 'AssetStackResponseDto' });

export const AssetResponseSchema = SanitizedAssetResponseSchema.extend(
  z.object({
    createdAt: isoDatetimeToDate.describe('The UTC timestamp when the asset was originally uploaded to Immich.'),
    ownerId: z.string().describe('Owner user ID'),
    owner: UserResponseSchema.optional(),
    libraryId: z
      .uuidv4()
      .nullish()
      .describe('Library ID')
      .meta(new HistoryBuilder().added('v1').deprecated('v1').getExtensions()),
    originalPath: z.string().describe('Original file path'),
    originalFileName: z.string().describe('Original file name'),
    fileCreatedAt: isoDatetimeToDate.describe(
      'The actual UTC timestamp when the file was created/captured, preserving timezone information. This is the authoritative timestamp for chronological sorting within timeline groups. Combined with timezone data, this can be used to determine the exact moment the photo was taken.',
    ),
    fileModifiedAt: isoDatetimeToDate.describe(
      'The UTC timestamp when the file was last modified on the filesystem. This reflects the last time the physical file was changed, which may be different from when the photo was originally taken.',
    ),
    updatedAt: isoDatetimeToDate.describe(
      'The UTC timestamp when the asset record was last updated in the database. This is automatically maintained by the database and reflects when any field in the asset was last modified.',
    ),
    isFavorite: z.boolean().describe('Is favorite'),
    isArchived: z.boolean().describe('Is archived'),
    isTrashed: z.boolean().describe('Is trashed'),
    isOffline: z.boolean().describe('Is offline'),
    visibility: AssetVisibilitySchema,
    exifInfo: ExifResponseSchema.optional(),
    tags: z.array(TagResponseSchema).optional(),
    people: z.array(PersonWithFacesResponseSchema).optional(),
    unassignedFaces: z.array(AssetFaceWithoutPersonResponseSchema).optional(),
    checksum: z.string().describe('Base64 encoded SHA1 hash'),
    stack: AssetStackResponseSchema.nullish(),
    duplicateId: z.string().nullish().describe('Duplicate group ID'),
    resized: z
      .boolean()
      .optional()
      .describe('Is resized')
      .meta(new HistoryBuilder().added('v1').deprecated('v1.113.0').getExtensions()),
    isEdited: z
      .boolean()
      .describe('Is edited')
      .meta(new HistoryBuilder().added('v2.5.0').beta('v2.5.0').getExtensions()),
  }).shape,
).meta({ id: 'AssetResponseDto' });

export class AssetResponseDto extends createZodDto(AssetResponseSchema, { codec: true }) {}

export type MapAsset = {
  createdAt: Date;
  updatedAt: Date;
  deletedAt: Date | null;
  id: string;
  updateId: string;
  status: AssetStatus;
  checksum: Buffer<ArrayBufferLike>;
  checksumAlgorithm: ChecksumAlgorithm;
  duplicateId: string | null;
  duration: string | null;
  edits?: ShallowDehydrateObject<AssetEditActionItem>[];
  exifInfo?: ShallowDehydrateObject<Selectable<Exif>> | null;
  faces?: ShallowDehydrateObject<AssetFace>[];
  fileCreatedAt: Date;
  fileModifiedAt: Date;
  files?: ShallowDehydrateObject<AssetFile>[];
  isExternal: boolean;
  isFavorite: boolean;
  isOffline: boolean;
  visibility: AssetVisibility;
  libraryId: string | null;
  livePhotoVideoId: string | null;
  localDateTime: Date;
  originalFileName: string;
  originalPath: string;
  owner?: ShallowDehydrateObject<User> | null;
  ownerId: string;
  stack?: (ShallowDehydrateObject<Stack> & { assets: Stack['assets'] }) | null;
  stackId: string | null;
  tags?: ShallowDehydrateObject<Tag>[];
  thumbhash: Buffer<ArrayBufferLike> | null;
  type: AssetType;
  width: number | null;
  height: number | null;
  isEdited: boolean;
};

export type AssetMapOptions = {
  stripMetadata?: boolean;
  withStack?: boolean;
  auth?: AuthDto;
};

const peopleWithFaces = (
  faces?: MaybeDehydrated<AssetFace>[],
  edits?: AssetEditActionItem[],
  assetDimensions?: ImageDimensions,
): PersonWithFacesResponseDto[] => {
  if (!faces) {
    return [];
  }

  const peopleFaces: Map<string, PersonWithFacesResponseDto> = new Map();

  for (const face of faces) {
    if (!face.person) {
      continue;
    }

    if (!peopleFaces.has(face.person.id)) {
      peopleFaces.set(face.person.id, {
        ...mapPerson(face.person),
        faces: [],
      });
    }
    const mappedFace = mapFacesWithoutPerson(face, edits, assetDimensions);
    peopleFaces.get(face.person.id)!.faces.push(mappedFace);
  }

  return [...peopleFaces.values()];
};

const mapStack = (entity: { stack?: Stack | null }) => {
  if (!entity.stack) {
    return null;
  }

  return {
    id: entity.stack.id,
    primaryAssetId: entity.stack.primaryAssetId,
    assetCount: entity.stack.assetCount ?? entity.stack.assets.length + 1,
  };
};

export function mapAsset(entity: MaybeDehydrated<MapAsset>, options: AssetMapOptions = {}): AssetResponseDto {
  const { stripMetadata = false, withStack = false } = options;

  if (stripMetadata) {
    const sanitizedAssetResponse: SanitizedAssetResponseDto = {
      id: entity.id,
      type: entity.type,
      originalMimeType: mimeTypes.lookup(entity.originalFileName),
      thumbhash: entity.thumbhash ? hexOrBufferToBase64(entity.thumbhash) : null,
      localDateTime: new Date(entity.localDateTime),
      duration: entity.duration,
      livePhotoVideoId: entity.livePhotoVideoId,
      hasMetadata: false,
      width: entity.width,
      height: entity.height,
    };
    return sanitizedAssetResponse as AssetResponseDto;
  }

  const assetDimensions = entity.exifInfo ? getDimensions(entity.exifInfo) : undefined;

  return {
    id: entity.id,
    createdAt: new Date(entity.createdAt),
    ownerId: entity.ownerId,
    owner: entity.owner ? mapUser(entity.owner) : undefined,
    libraryId: entity.libraryId,
    type: entity.type,
    originalPath: entity.originalPath,
    originalFileName: entity.originalFileName,
    originalMimeType: mimeTypes.lookup(entity.originalFileName),
    thumbhash: entity.thumbhash ? hexOrBufferToBase64(entity.thumbhash) : null,
    fileCreatedAt: new Date(entity.fileCreatedAt),
    fileModifiedAt: new Date(entity.fileModifiedAt),
    localDateTime: new Date(entity.localDateTime),
    updatedAt: new Date(entity.updatedAt),
    isFavorite: options.auth?.user.id === entity.ownerId && entity.isFavorite,
    isArchived: entity.visibility === AssetVisibility.Archive,
    isTrashed: !!entity.deletedAt,
    visibility: entity.visibility,
    duration: entity.duration,
    exifInfo: entity.exifInfo ? mapExif(entity.exifInfo) : undefined,
    livePhotoVideoId: entity.livePhotoVideoId,
    tags: entity.tags?.map((tag) => mapTag(tag)),
    people: peopleWithFaces(entity.faces, entity.edits, assetDimensions),
    unassignedFaces: entity.faces
      ?.filter((face) => !face.person)
      .map((face) => mapFacesWithoutPerson(face, entity.edits, assetDimensions)),
    checksum: hexOrBufferToBase64(entity.checksum)!,
    stack: withStack ? mapStack(entity) : undefined,
    isOffline: entity.isOffline,
    hasMetadata: true,
    duplicateId: entity.duplicateId,
    resized: true,
    width: entity.width,
    height: entity.height,
    isEdited: entity.isEdited,
  };
}