ddex-json-codec 0.1.0 → 0.2.0

package/README.md

@@ -1,16 +1,16 @@
 # ddex-json-codec
 
-DDEX ERN規格のXML/JSON相互変換ライブラリ（TypeScript）
+Bidirectional XML/JSON codec for the DDEX ERN (Electronic Release Notification) standard, written in TypeScript.
 
-## 特徴
+## Features
 
-- ERN XMLからTypeScript型付きオブジェクトへの変換、およびその逆変換
-- ERN 3.8系 / 4系に対応（4系は未実装）
-- バージョン自動検出
-- [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) ベース
+- Convert ERN XML to typed TypeScript objects and back
+- Supports ERN 3.8.x (3.8 - 3.8.3) and ERN 4.x (4.1 - 4.3.2)
+- Automatic version detection from namespace URI
+- Built on [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser)
 - Node.js >= 20
 
-## インストール
+## Install
 
 ```bash
 npm install ddex-json-codec
@@ -18,66 +18,66 @@ npm install ddex-json-codec
 pnpm add ddex-json-codec
 ```
 
-## 使い方
+## Usage
 
-### XML → JSON
+### XML to JSON
 
 ```typescript
 import { xmlToJson } from 'ddex-json-codec';
 
 const message = xmlToJson(xmlString);
-console.log(message.ernVersion); // "3.8.1"
+console.log(message.ernVersion); // "3.8.2"
 console.log(message.resourceList); // SoundRecording[]
 ```
 
-### JSON → XML
+### JSON to XML
 
 ```typescript
 import { jsonToXml } from 'ddex-json-codec';
 
 const xml = jsonToXml(message);
-// バージョン指定も可
+// Optionally specify a target version
 const xml382 = jsonToXml(message, '3.8.2');
 ```
 
-### バージョン検出
+### Version Detection
 
 ```typescript
 import { detectVersion } from 'ddex-json-codec';
 
-const version = detectVersion(xmlString); // "3.8.1"
+const version = detectVersion(xmlString); // "4.3"
 ```
 
-## 対応バージョン
+## Supported Versions
 
-| ERN バージョン | 状態 |
+| ERN Version | Status |
 |---|---|
-| 3.8 | 実装済み |
-| 3.8.1 | 実装済み |
-| 3.8.2 | 実装済み |
-| 3.8.3 | 実装済み |
-| 4.1 | 未実装 |
-| 4.1.1 | 未実装 |
-| 4.2 | 未実装 |
-| 4.3 | 未実装 |
-| 4.3.1 | 未実装 |
-| 4.3.2 | 未実装 |
-
-## API リファレンス
+| 3.8 | Supported |
+| 3.8.1 | Supported |
+| 3.8.2 | Supported |
+| 3.8.3 | Supported |
+| 4.1 | Supported |
+| 4.1.1 | Supported |
+| 4.2 | Supported |
+| 4.3 | Supported |
+| 4.3.1 | Supported |
+| 4.3.2 | Supported |
+
+## API
 
 ### `xmlToJson(xml: string): DdexMessage`
 
-ERN XMLを解析し、型付きオブジェクトを返す。バージョンは自動検出される。
+Parse an ERN XML string into a typed object. Version is auto-detected.
 
 ### `jsonToXml(message: DdexMessage, version?: ErnVersion): string`
 
-`DdexMessage` をERN XMLに変換する。`version` 省略時は `message.ernVersion` を使用。
+Convert a `DdexMessage` back to an ERN XML string. Falls back to `message.ernVersion` when `version` is omitted.
 
 ### `detectVersion(xml: string): ErnVersion`
 
-ERN XMLのnamespace URIからバージョンを検出して返す。
+Detect the ERN version from namespace URI or `MessageSchemaVersionId` attribute.
 
-### 型
+### Types
 
 ```typescript
 interface DdexMessage {
@@ -85,21 +85,24 @@ interface DdexMessage {
   messageHeader: MessageHeader;
   updateIndicator?: string;
   resourceList: SoundRecording[];
+  imageList?: Image[];
   releaseList: Release[];
   dealList: ReleaseDeal[];
-  partyList?: Party[];              // 4系のみ
-  trackReleaseList?: TrackRelease[]; // 4系のみ
+  partyList?: Party[];              // ERN 4.x only
+  trackReleaseList?: TrackRelease[]; // ERN 4.x only
 }
 ```
 
-エクスポートされる型一覧:
+Exported types:
 
 `DdexMessage`, `ErnVersion`, `ErnMajorVersion`, `MessageHeader`, `MessageParty`,
-`SoundRecording`, `Release`, `TrackRelease`, `ResourceGroup`, `ReleaseResourceReference`,
+`SoundRecording`, `TechnicalSoundRecordingDetails`,
+`Image`, `ImageId`, `ImageDetailsByTerritory`, `TechnicalImageDetails`, `FileDetails`, `HashSum`,
+`Release`, `TrackRelease`, `ResourceGroup`, `ReleaseResourceReference`,
 `ReleaseDeal`, `Deal`, `DealTerms`, `Usage`,
-`Party`, `Artist`, `DisplayArtist`, `ResourceContributor`, `IndirectResourceContributor`,
-`TextWithAttribute`, `Genre`, `PLine`, `CLine`, `Title`
+`Party`, `Artist`, `ArtistRole`, `DisplayArtist`, `ResourceContributor`, `IndirectResourceContributor`, `Contributor`,
+`TextWithAttribute`, `Genre`, `PLine`, `CLine`, `Title`, `DisplayTitle`
 
-## ライセンス
+## License
 
 [MIT](./LICENSE.md)

package/dist/index.d.mts

@@ -45,13 +45,21 @@ interface PartyName {
   fullNameIndexed?: string;
   languageAndScriptCode?: string;
 }
+interface ArtistRole {
+  role: string;
+  /** UserDefined時の属性 */
+  namespace?: string;
+  userDefinedValue?: string;
+}
 interface Artist {
-  /** 解決済みの名前（3.8系: FullNameから直接取得、4系: PartyListから解決） */
+  /** 解決済みのデフォルト名（3.8系: FullNameから直接取得、4系: PartyListの最初のFullName） */
   name: string;
+  /** 4系のみ: 多言語名（PartyListのPartyName[]をそのまま保持） */
+  names?: PartyName[];
   /** 4系のみ: 元の参照ID（ラウンドトリップ用） */
   partyReference?: string;
   partyId?: string[];
-  roles?: string[];
+  roles?: ArtistRole[];
 }
 interface DisplayArtist {
   artist: Artist;
@@ -79,6 +87,43 @@ interface Contributor {
   sequenceNumber?: number;
 }
 //#endregion
+//#region src/types/image.d.ts
+interface Image {
+  resourceReference: string;
+  type?: string;
+  imageId?: ImageId;
+  /** 3.8系: territory別の詳細 */
+  detailsByTerritory?: ImageDetailsByTerritory[];
+  /** 4系: フラット */
+  parentalWarningType?: string;
+  technicalDetails?: TechnicalImageDetails;
+}
+interface ImageId {
+  proprietaryId?: string;
+  proprietaryIdNamespace?: string;
+}
+interface ImageDetailsByTerritory {
+  territoryCode: string[];
+  parentalWarningType?: string;
+  technicalDetails?: TechnicalImageDetails;
+}
+interface TechnicalImageDetails {
+  technicalResourceDetailsReference?: string;
+  imageCodecType?: string;
+  imageHeight?: number;
+  imageWidth?: number;
+  file?: FileDetails;
+}
+interface FileDetails {
+  fileName?: string;
+  uri?: string;
+  hashSum?: HashSum;
+}
+interface HashSum {
+  algorithm?: string;
+  hashSumValue?: string;
+}
+//#endregion
 //#region src/types/sound-recording.d.ts
 interface SoundRecording {
   resourceReference: string;
@@ -107,9 +152,21 @@ interface ReferenceTitle$1 {
   titleText: string;
   subTitle?: string;
 }
+interface TechnicalSoundRecordingDetails {
+  technicalResourceDetailsReference?: string;
+  audioCodecType?: string;
+  bitRate?: number;
+  bitRateUnit?: string;
+  numberOfChannels?: number;
+  samplingRate?: number;
+  samplingRateUnit?: string;
+  isPreview?: boolean;
+  file?: FileDetails;
+}
 interface SoundRecordingDetailsByTerritory {
   territoryCode: string[];
   displayArtists?: DisplayArtist[];
+  displayArtistName?: string;
   titles?: Title[];
   labelName?: string;
   pLine?: PLine;
@@ -118,6 +175,7 @@ interface SoundRecordingDetailsByTerritory {
   sequenceNumber?: number;
   resourceContributors?: ResourceContributor[];
   indirectResourceContributors?: IndirectResourceContributor[];
+  technicalDetails?: TechnicalSoundRecordingDetails[];
 }
 //#endregion
 //#region src/types/release.d.ts
@@ -255,6 +313,7 @@ interface DdexMessage {
   messageHeader: MessageHeader;
   updateIndicator?: string;
   resourceList: SoundRecording[];
+  imageList?: Image[];
   releaseList: Release[];
   dealList: ReleaseDeal[];
   /** 4系のみ: PartyList（ラウンドトリップ用に保持） */
@@ -287,4 +346,4 @@ declare function jsonToXml(message: DdexMessage, version?: ErnVersion): string;
  */
 declare function detectVersion(xml: string): ErnVersion;
 //#endregion
-export { type Artist, type CLine, type Contributor, type DdexMessage, type Deal, type DealTerms, type DisplayArtist, type DisplayTitle, type ErnMajorVersion, type ErnVersion, type Genre, type IndirectResourceContributor, type MessageHeader, type MessageParty, type PLine, type Party, type Release, type ReleaseDeal, type ReleaseResourceReference, type ResourceContributor, type ResourceGroup, type SoundRecording, type TextWithAttribute, type Title, type TrackRelease, type Usage, detectVersion, jsonToXml, xmlToJson };
+export { type Artist, type ArtistRole, type CLine, type Contributor, type DdexMessage, type Deal, type DealTerms, type DisplayArtist, type DisplayTitle, type ErnMajorVersion, type ErnVersion, type FileDetails, type Genre, type HashSum, type Image, type ImageDetailsByTerritory, type ImageId, type IndirectResourceContributor, type MessageHeader, type MessageParty, type PLine, type Party, type Release, type ReleaseDeal, type ReleaseResourceReference, type ResourceContributor, type ResourceGroup, type SoundRecording, type TechnicalImageDetails, type TechnicalSoundRecordingDetails, type TextWithAttribute, type Title, type TrackRelease, type Usage, detectVersion, jsonToXml, xmlToJson };

package/dist/index.mjs

@@ -146,6 +146,7 @@ var Ern38Converter = class {
 			messageHeader: this.parseMessageHeader(root.MessageHeader),
 			updateIndicator: root.UpdateIndicator ?? void 0,
 			resourceList: this.parseSoundRecordings(root.ResourceList),
+			imageList: this.parseImages(root.ResourceList),
 			releaseList: this.parseReleases(root.ReleaseList),
 			dealList: this.parseDealList(root.DealList)
 		};
@@ -209,6 +210,7 @@ var Ern38Converter = class {
 		return {
 			territoryCode: ensureArray(raw.TerritoryCode),
 			displayArtists: this.parseDisplayArtists(raw.DisplayArtist),
+			displayArtistName: Array.isArray(raw.DisplayArtistName) ? raw.DisplayArtistName[0] : raw.DisplayArtistName ?? void 0,
 			titles: this.parseTitles(raw.Title),
 			labelName: raw.LabelName ?? void 0,
 			pLine: raw.PLine ? this.parsePLine(ensureArray(raw.PLine)[0]) : void 0,
@@ -216,7 +218,74 @@ var Ern38Converter = class {
 			parentalWarningType: raw.ParentalWarningType ?? void 0,
 			sequenceNumber: raw.SequenceNumber ? Number(raw.SequenceNumber) : void 0,
 			resourceContributors: this.parseResourceContributors(raw.ResourceContributor),
-			indirectResourceContributors: this.parseIndirectResourceContributors(raw.IndirectResourceContributor)
+			indirectResourceContributors: this.parseIndirectResourceContributors(raw.IndirectResourceContributor),
+			technicalDetails: raw.TechnicalSoundRecordingDetails ? ensureArray(raw.TechnicalSoundRecordingDetails).map((td) => this.parseTechnicalSoundRecordingDetails(td)) : void 0
+		};
+	}
+	parseTechnicalSoundRecordingDetails(raw) {
+		const bitRate = raw.BitRate;
+		const samplingRate = raw.SamplingRate;
+		return {
+			technicalResourceDetailsReference: raw.TechnicalResourceDetailsReference ?? void 0,
+			audioCodecType: raw.AudioCodecType ?? void 0,
+			bitRate: bitRate ? Number(typeof bitRate === "string" ? bitRate : bitRate["#text"]) : void 0,
+			bitRateUnit: typeof bitRate === "object" ? bitRate["@_UnitOfMeasure"] ?? void 0 : void 0,
+			numberOfChannels: raw.NumberOfChannels ? Number(raw.NumberOfChannels) : void 0,
+			samplingRate: samplingRate ? Number(typeof samplingRate === "string" ? samplingRate : samplingRate["#text"]) : void 0,
+			samplingRateUnit: typeof samplingRate === "object" ? samplingRate["@_UnitOfMeasure"] ?? void 0 : void 0,
+			isPreview: raw.IsPreview === "true" ? true : raw.IsPreview === "false" ? false : void 0,
+			file: raw.File ? this.parseFileDetails(raw.File) : void 0
+		};
+	}
+	parseImages(resourceList) {
+		if (!resourceList) return void 0;
+		const images = ensureArray(resourceList.Image);
+		if (images.length === 0) return void 0;
+		return images.map((img) => this.parseImage(img));
+	}
+	parseImage(raw) {
+		return {
+			resourceReference: raw.ResourceReference,
+			type: raw.ImageType ?? void 0,
+			imageId: raw.ImageId ? this.parseImageId(raw.ImageId) : void 0,
+			detailsByTerritory: raw.ImageDetailsByTerritory ? ensureArray(raw.ImageDetailsByTerritory).map((d) => this.parseImageDetailsByTerritory(d)) : void 0
+		};
+	}
+	parseImageId(raw) {
+		const propId = raw.ProprietaryId;
+		if (!propId) return void 0;
+		return {
+			proprietaryId: typeof propId === "string" ? propId : propId["#text"] ?? "",
+			proprietaryIdNamespace: typeof propId === "object" ? propId["@_Namespace"] ?? void 0 : void 0
+		};
+	}
+	parseImageDetailsByTerritory(raw) {
+		return {
+			territoryCode: ensureArray(raw.TerritoryCode),
+			parentalWarningType: raw.ParentalWarningType ?? void 0,
+			technicalDetails: raw.TechnicalImageDetails ? this.parseTechnicalImageDetails(Array.isArray(raw.TechnicalImageDetails) ? raw.TechnicalImageDetails[0] : raw.TechnicalImageDetails) : void 0
+		};
+	}
+	parseTechnicalImageDetails(raw) {
+		return {
+			technicalResourceDetailsReference: raw.TechnicalResourceDetailsReference ?? void 0,
+			imageCodecType: raw.ImageCodecType ?? void 0,
+			imageHeight: raw.ImageHeight ? Number(raw.ImageHeight) : void 0,
+			imageWidth: raw.ImageWidth ? Number(raw.ImageWidth) : void 0,
+			file: raw.File ? this.parseFileDetails(raw.File) : void 0
+		};
+	}
+	parseFileDetails(raw) {
+		return {
+			fileName: raw.FileName ?? void 0,
+			uri: raw.URI ?? void 0,
+			hashSum: raw.HashSum ? this.parseHashSum(raw.HashSum) : void 0
+		};
+	}
+	parseHashSum(raw) {
+		return {
+			algorithm: raw.HashSumAlgorithmType ?? raw.Algorithm ?? void 0,
+			hashSumValue: raw.HashSum ?? raw.HashSumValue ?? void 0
 		};
 	}
 	parseReleases(releaseList) {
@@ -351,11 +420,21 @@ var Ern38Converter = class {
 		return artists.map((a) => ({
 			artist: {
 				name: a.PartyName?.FullName ?? "",
-				roles: a.ArtistRole ? ensureArray(a.ArtistRole) : void 0
+				roles: a.ArtistRole ? this.parseArtistRoles(a.ArtistRole) : void 0
 			},
 			sequenceNumber: a["@_SequenceNumber"] ? Number(a["@_SequenceNumber"]) : void 0
 		}));
 	}
+	parseArtistRoles(raw) {
+		return ensureArray(raw).map((r) => {
+			if (typeof r === "string") return { role: r };
+			return {
+				role: r["#text"] ?? "",
+				namespace: r["@_Namespace"] ?? void 0,
+				userDefinedValue: r["@_UserDefinedValue"] ?? void 0
+			};
+		});
+	}
 	parseResourceContributors(raw) {
 		if (!raw) return void 0;
 		const contributors = ensureArray(raw);
@@ -432,6 +511,7 @@ var Ern4Converter = class {
 			ernVersion: version,
 			messageHeader: this.parseMessageHeader(root.MessageHeader),
 			resourceList: this.parseSoundRecordings(root.ResourceList),
+			imageList: this.parseImages(root.ResourceList),
 			releaseList: this.parseReleases(root.ReleaseList),
 			dealList: this.parseDealList(root.DealList),
 			partyList,
@@ -472,10 +552,13 @@ var Ern4Converter = class {
 			partyId: partyIds.length > 0 ? partyIds : void 0
 		};
 	}
-	resolveArtistName(partyReference) {
+	resolveParty(partyReference) {
 		const party = this.partyIndex.get(partyReference);
-		if (!party?.partyName?.length) return partyReference;
-		return party.partyName[0].fullName;
+		if (!party?.partyName?.length) return { name: partyReference };
+		return {
+			name: party.partyName[0].fullName,
+			names: party.partyName.length > 1 ? party.partyName : void 0
+		};
 	}
 	parseMessageHeader(raw) {
 		return {
@@ -538,6 +621,43 @@ var Ern4Converter = class {
 			catalogNumber: raw.CatalogNumber ?? void 0
 		};
 	}
+	parseImages(resourceList) {
+		if (!resourceList) return void 0;
+		const images = ensureArray(resourceList.Image);
+		if (images.length === 0) return void 0;
+		return images.map((img) => {
+			const result = {
+				resourceReference: img.ResourceReference,
+				type: img.Type ?? void 0,
+				parentalWarningType: img.ParentalWarningType ?? void 0
+			};
+			if (img.ResourceId) {
+				const propId = img.ResourceId.ProprietaryId;
+				if (propId) result.imageId = {
+					proprietaryId: typeof propId === "string" ? propId : propId["#text"] ?? "",
+					proprietaryIdNamespace: typeof propId === "object" ? propId["@_Namespace"] ?? void 0 : void 0
+				};
+			}
+			if (img.TechnicalDetails) {
+				const td = Array.isArray(img.TechnicalDetails) ? img.TechnicalDetails[0] : img.TechnicalDetails;
+				result.technicalDetails = {
+					technicalResourceDetailsReference: td.TechnicalResourceDetailsReference ?? void 0,
+					imageCodecType: td.ImageCodecType ?? void 0,
+					imageHeight: td.ImageHeight ? Number(td.ImageHeight) : void 0,
+					imageWidth: td.ImageWidth ? Number(td.ImageWidth) : void 0,
+					file: td.File ? {
+						uri: td.File.URI ?? void 0,
+						fileName: td.File.FileName ?? void 0,
+						hashSum: td.File.HashSum ? {
+							algorithm: td.File.HashSum.Algorithm ?? void 0,
+							hashSumValue: td.File.HashSum.HashSumValue ?? void 0
+						} : void 0
+					} : void 0
+				};
+			}
+			return result;
+		});
+	}
 	parseReleases(releaseList) {
 		if (!releaseList) return [];
 		return ensureArray(releaseList.Release).map((r) => this.parseRelease(r));
@@ -675,23 +795,38 @@ var Ern4Converter = class {
 		if (artists.length === 0) return void 0;
 		return artists.map((a) => {
 			const partyRef = a.ArtistPartyReference;
+			const resolved = partyRef ? this.resolveParty(partyRef) : {
+				name: a.PartyName?.FullName ?? "",
+				names: void 0
+			};
 			return {
 				artist: {
-					name: partyRef ? this.resolveArtistName(partyRef) : a.PartyName?.FullName ?? "",
+					name: resolved.name,
+					names: resolved.names,
 					partyReference: partyRef ?? void 0,
-					roles: a.DisplayArtistRole ? ensureArray(a.DisplayArtistRole) : void 0
+					roles: a.DisplayArtistRole ? this.parseArtistRoles(a.DisplayArtistRole) : void 0
 				},
 				sequenceNumber: a["@_SequenceNumber"] ? Number(a["@_SequenceNumber"]) : void 0
 			};
 		});
 	}
+	parseArtistRoles(raw) {
+		return ensureArray(raw).map((r) => {
+			if (typeof r === "string") return { role: r };
+			return {
+				role: r["#text"] ?? "",
+				namespace: r["@_Namespace"] ?? void 0,
+				userDefinedValue: r["@_UserDefinedValue"] ?? void 0
+			};
+		});
+	}
 	parseContributors(raw) {
 		if (!raw) return void 0;
 		const contributors = ensureArray(raw);
 		if (contributors.length === 0) return void 0;
 		return contributors.map((c) => {
 			const partyRef = c.ContributorPartyReference;
-			const name = partyRef ? this.resolveArtistName(partyRef) : void 0;
+			const name = partyRef ? this.resolveParty(partyRef).name : void 0;
 			return {
 				contributorPartyReference: partyRef ?? "",
 				name,
@@ -749,7 +884,7 @@ var Ern38Builder = class {
 			"@_xsi:schemaLocation": `${nsUri} ${nsUri}/release-notification.xsd`,
 			MessageHeader: this.buildMessageHeader(message.messageHeader),
 			...message.updateIndicator ? { UpdateIndicator: message.updateIndicator } : {},
-			ResourceList: this.buildResourceList(message.resourceList),
+			ResourceList: this.buildResourceList(message.resourceList, message.imageList),
 			ReleaseList: this.buildReleaseList(message.releaseList),
 			DealList: this.buildDealList(message.dealList)
 		} };
@@ -775,8 +910,10 @@ var Ern38Builder = class {
 		if (party.tradingName) result.TradingName = party.tradingName;
 		return result;
 	}
-	buildResourceList(soundRecordings) {
-		return { SoundRecording: soundRecordings.map((sr) => this.buildSoundRecording(sr)) };
+	buildResourceList(soundRecordings, images) {
+		const result = { SoundRecording: soundRecordings.map((sr) => this.buildSoundRecording(sr)) };
+		if (images?.length) result.Image = images.map((img) => this.buildImage(img));
+		return result;
 	}
 	buildSoundRecording(sr) {
 		const result = {};
@@ -804,6 +941,7 @@ var Ern38Builder = class {
 		result.TerritoryCode = d.territoryCode;
 		if (d.titles) result.Title = d.titles.map((t) => this.buildTitle(t));
 		if (d.displayArtists) result.DisplayArtist = d.displayArtists.map((a) => this.buildDisplayArtist(a));
+		if (d.displayArtistName) result.DisplayArtistName = d.displayArtistName;
 		if (d.resourceContributors) result.ResourceContributor = d.resourceContributors.map((c) => this.buildResourceContributor(c));
 		if (d.indirectResourceContributors) result.IndirectResourceContributor = d.indirectResourceContributors.map((c) => this.buildIndirectResourceContributor(c));
 		if (d.labelName) result.LabelName = d.labelName;
@@ -811,6 +949,74 @@ var Ern38Builder = class {
 		if (d.sequenceNumber != null) result.SequenceNumber = String(d.sequenceNumber);
 		if (d.genre) result.Genre = this.buildGenre(d.genre);
 		if (d.parentalWarningType) result.ParentalWarningType = d.parentalWarningType;
+		if (d.technicalDetails) result.TechnicalSoundRecordingDetails = d.technicalDetails.map((td) => this.buildTechnicalSoundRecordingDetails(td));
+		return result;
+	}
+	buildTechnicalSoundRecordingDetails(td) {
+		const result = {};
+		if (td.technicalResourceDetailsReference) result.TechnicalResourceDetailsReference = td.technicalResourceDetailsReference;
+		if (td.audioCodecType) result.AudioCodecType = td.audioCodecType;
+		if (td.bitRate != null) result.BitRate = td.bitRateUnit ? {
+			"#text": String(td.bitRate),
+			"@_UnitOfMeasure": td.bitRateUnit
+		} : String(td.bitRate);
+		if (td.numberOfChannels != null) result.NumberOfChannels = String(td.numberOfChannels);
+		if (td.samplingRate != null) result.SamplingRate = td.samplingRateUnit ? {
+			"#text": String(td.samplingRate),
+			"@_UnitOfMeasure": td.samplingRateUnit
+		} : String(td.samplingRate);
+		if (td.isPreview != null) result.IsPreview = String(td.isPreview);
+		if (td.file) {
+			const file = {};
+			if (td.file.fileName) file.FileName = td.file.fileName;
+			if (td.file.uri) file.URI = td.file.uri;
+			if (td.file.hashSum) {
+				file.HashSum = {};
+				if (td.file.hashSum.algorithm) file.HashSum.HashSumAlgorithmType = td.file.hashSum.algorithm;
+				if (td.file.hashSum.hashSumValue) file.HashSum.HashSum = td.file.hashSum.hashSumValue;
+			}
+			result.File = file;
+		}
+		return result;
+	}
+	buildImage(img) {
+		const result = {};
+		if (img.type) result.ImageType = img.type;
+		if (img.imageId) {
+			const id = {};
+			if (img.imageId.proprietaryId) id.ProprietaryId = img.imageId.proprietaryIdNamespace ? {
+				"#text": img.imageId.proprietaryId,
+				"@_Namespace": img.imageId.proprietaryIdNamespace
+			} : img.imageId.proprietaryId;
+			result.ImageId = id;
+		}
+		result.ResourceReference = img.resourceReference;
+		if (img.detailsByTerritory) result.ImageDetailsByTerritory = img.detailsByTerritory.map((d) => {
+			const dbt = {};
+			dbt.TerritoryCode = d.territoryCode;
+			if (d.parentalWarningType) dbt.ParentalWarningType = d.parentalWarningType;
+			if (d.technicalDetails) dbt.TechnicalImageDetails = this.buildTechnicalImageDetails(d.technicalDetails);
+			return dbt;
+		});
+		return result;
+	}
+	buildTechnicalImageDetails(td) {
+		const result = {};
+		if (td.technicalResourceDetailsReference) result.TechnicalResourceDetailsReference = td.technicalResourceDetailsReference;
+		if (td.imageCodecType) result.ImageCodecType = td.imageCodecType;
+		if (td.imageHeight != null) result.ImageHeight = String(td.imageHeight);
+		if (td.imageWidth != null) result.ImageWidth = String(td.imageWidth);
+		if (td.file) {
+			const file = {};
+			if (td.file.fileName) file.FileName = td.file.fileName;
+			if (td.file.uri) file.URI = td.file.uri;
+			if (td.file.hashSum) {
+				file.HashSum = {};
+				if (td.file.hashSum.algorithm) file.HashSum.HashSumAlgorithmType = td.file.hashSum.algorithm;
+				if (td.file.hashSum.hashSumValue) file.HashSum.HashSum = td.file.hashSum.hashSumValue;
+			}
+			result.File = file;
+		}
 		return result;
 	}
 	buildReleaseList(releases) {
@@ -909,9 +1115,20 @@ var Ern38Builder = class {
 		const result = {};
 		if (da.sequenceNumber != null) result["@_SequenceNumber"] = String(da.sequenceNumber);
 		result.PartyName = { FullName: da.artist.name };
-		if (da.artist.roles?.length) result.ArtistRole = da.artist.roles.length === 1 ? da.artist.roles[0] : da.artist.roles;
+		if (da.artist.roles?.length) {
+			const builtRoles = da.artist.roles.map((r) => this.buildArtistRole(r));
+			result.ArtistRole = builtRoles.length === 1 ? builtRoles[0] : builtRoles;
+		}
 		return result;
 	}
+	buildArtistRole(r) {
+		if (r.userDefinedValue) return {
+			"#text": r.role,
+			...r.namespace ? { "@_Namespace": r.namespace } : {},
+			"@_UserDefinedValue": r.userDefinedValue
+		};
+		return r.role;
+	}
 	buildResourceContributor(c) {
 		const result = {};
 		if (c.sequenceNumber != null) result["@_SequenceNumber"] = String(c.sequenceNumber);
@@ -970,7 +1187,7 @@ var Ern4Builder = class {
 			"@_LanguageAndScriptCode": "en",
 			MessageHeader: this.buildMessageHeader(message.messageHeader),
 			PartyList: this.buildPartyList(message.partyList ?? []),
-			ResourceList: this.buildResourceList(message.resourceList, version),
+			ResourceList: this.buildResourceList(message.resourceList, message.imageList, version),
 			ReleaseList: this.buildReleaseList(message.releaseList, message.trackReleaseList),
 			DealList: this.buildDealList(message.dealList)
 		} };
@@ -1009,8 +1226,40 @@ var Ern4Builder = class {
 		if (party.partyId?.length) result.PartyId = party.partyId.map((id) => id);
 		return result;
 	}
-	buildResourceList(soundRecordings, _version) {
-		return { SoundRecording: soundRecordings.map((sr) => this.buildSoundRecording(sr)) };
+	buildResourceList(soundRecordings, images, _version) {
+		const result = { SoundRecording: soundRecordings.map((sr) => this.buildSoundRecording(sr)) };
+		if (images?.length) result.Image = images.map((img) => this.buildImage(img));
+		return result;
+	}
+	buildImage(img) {
+		const result = {};
+		result.ResourceReference = img.resourceReference;
+		if (img.type) result.Type = img.type;
+		if (img.imageId?.proprietaryId) result.ResourceId = { ProprietaryId: img.imageId.proprietaryIdNamespace ? {
+			"#text": img.imageId.proprietaryId,
+			"@_Namespace": img.imageId.proprietaryIdNamespace
+		} : img.imageId.proprietaryId };
+		if (img.parentalWarningType) result.ParentalWarningType = img.parentalWarningType;
+		if (img.technicalDetails) {
+			const td = {};
+			if (img.technicalDetails.technicalResourceDetailsReference) td.TechnicalResourceDetailsReference = img.technicalDetails.technicalResourceDetailsReference;
+			if (img.technicalDetails.imageCodecType) td.ImageCodecType = img.technicalDetails.imageCodecType;
+			if (img.technicalDetails.imageHeight != null) td.ImageHeight = String(img.technicalDetails.imageHeight);
+			if (img.technicalDetails.imageWidth != null) td.ImageWidth = String(img.technicalDetails.imageWidth);
+			if (img.technicalDetails.file) {
+				const file = {};
+				if (img.technicalDetails.file.uri) file.URI = img.technicalDetails.file.uri;
+				if (img.technicalDetails.file.fileName) file.FileName = img.technicalDetails.file.fileName;
+				if (img.technicalDetails.file.hashSum) {
+					file.HashSum = {};
+					if (img.technicalDetails.file.hashSum.algorithm) file.HashSum.Algorithm = img.technicalDetails.file.hashSum.algorithm;
+					if (img.technicalDetails.file.hashSum.hashSumValue) file.HashSum.HashSumValue = img.technicalDetails.file.hashSum.hashSumValue;
+				}
+				td.File = file;
+			}
+			result.TechnicalDetails = td;
+		}
+		return result;
 	}
 	buildSoundRecording(sr) {
 		const result = {};
@@ -1131,9 +1380,20 @@ var Ern4Builder = class {
 		const result = {};
 		if (da.sequenceNumber != null) result["@_SequenceNumber"] = String(da.sequenceNumber);
 		if (da.artist.partyReference) result.ArtistPartyReference = da.artist.partyReference;
-		if (da.artist.roles?.length) result.DisplayArtistRole = da.artist.roles.length === 1 ? da.artist.roles[0] : da.artist.roles;
+		if (da.artist.roles?.length) {
+			const builtRoles = da.artist.roles.map((r) => this.buildArtistRole(r));
+			result.DisplayArtistRole = builtRoles.length === 1 ? builtRoles[0] : builtRoles;
+		}
 		return result;
 	}
+	buildArtistRole(r) {
+		if (r.userDefinedValue) return {
+			"#text": r.role,
+			...r.namespace ? { "@_Namespace": r.namespace } : {},
+			"@_UserDefinedValue": r.userDefinedValue
+		};
+		return r.role;
+	}
 	buildContributor(c) {
 		const result = {};
 		if (c.sequenceNumber != null) result["@_SequenceNumber"] = String(c.sequenceNumber);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ddex-json-codec",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DDEX ERN XML ↔ JSON converter for TypeScript",
   "license": "MIT",
   "author": "kazhs",