iot-metadata

NFT 메타데이터 검증 및 마이그레이션 라이브러리입니다.

설치

yarn add @apot-platforms/iot-metadata
# 또는
npm install @apot-platforms/iot-metadata

사용 방법

메타데이터 검증

import { validateMetadata } from '@apot-platforms/iot-metadata';

const metadata = {
  name: "테스트 NFT",
  image: "https://example.com/image.jpg",
  description: "테스트 설명",
  version: "0.2",
  isAllowCollectChecked: false,
  artworkInformation: {
    collectionId: 1,
    salesDisplayStatus: "SALES_AND_DISPLAY",
    tags: ["테스트"],
    createDate: new Date("2023-01-01"),
    willContinuousPublication: true,
    willAnnouncement: true,
  }
};

const result = validateMetadata(metadata);
if (result.success) {
  console.log('메타데이터가 유효합니다:', result.data);
} else {
  console.error('메타데이터가 유효하지 않습니다:', result.error);
}

메타데이터 파싱 및 버전 변환

import { parseMetadata } from '@apot-platforms/iot-metadata';

// V1 메타데이터
const v1Metadata = {
  name: "테스트 NFT",
  image: "https://example.com/image.jpg",
  description: "테스트 설명",
  version: "0.1",
  isAllowCollectChecked: false,
  copyright: {
    email: "[email protected]",
    phone: "+821012345678",
    phoneCountryCode: "KR",
    willContinuousPublication: true,
    nationality: "KR",
    willAnnouncement: true,
    postcode: "12345",
    address: "서울시 강남구",
    detailAddress: "테스트 빌딩",
    createDate: new Date("2023-01-01"),
  }
};

try {
  // V1 메타데이터를 V2로 변환
  const v2Metadata = parseMetadata(v1Metadata);
  console.log('변환된 메타데이터:', v2Metadata);
} catch (error) {
  console.error('메타데이터 변환 중 오류 발생:', error);
}

스키마 사용

라이브러리는 기본적으로 최신 버전(V2)의 스키마와 타입을 직접 export합니다.

// 기본 스키마는 모두 최신 버전(V2)입니다
import { 
  metadataSchema,
  artworkInformationSchema,
  baseSchema,
  ccScopeSchema,
  copyrightSchema,
  aiUsedSchema
} from '@apot-platforms/iot-metadata';

이전 버전(V1)이나 특정 버전의 스키마가 필요한 경우, 네임스페이스를 통해 접근합니다:

// V1 버전 스키마에 접근하기
import { V1 } from '@apot-platforms/iot-metadata';

// V1 스키마 사용
const v1MetadataResult = V1.metadataSchema.safeParse(data);

버전 관리 유틸리티 함수

import { 
  getSchemaByVersion, 
  validateMetadata, 
  parseMetadata 
} from '@apot-platforms/iot-metadata';

// 버전별 스키마 가져오기
const v1Schema = getSchemaByVersion("0.1");
const v2Schema = getSchemaByVersion("0.2");

// 자동 버전 감지하여 검증
const result = validateMetadata(metadata);

// 버전 변환 및 검증
const latestMetadata = parseMetadata(anyVersionMetadata);

타입 정의

기본적으로 최신 버전(V3)의 타입을 직접 export합니다:

import type { 
  NFTMetadata, 
  ArtworkInformation, 
  CCScope, 
  Copyright, 
  AITool,
  AIUsed,
  FileInformation 
} from '@apot-platforms/iot-metadata';

// NFTMetadata는 최신 버전(V3)의 타입입니다
const metadata: NFTMetadata = {
  // ...
};

V3 타입 추론 문제 해결

V3에서는 복잡한 zod 스키마로 인한 타입 추론 문제를 해결하기 위해 별도의 interface를 제공합니다:

// ✅ 권장: interface 사용 (타입 추론 문제 없음)
import type { AIUsed, AITool } from '@apot-platforms/iot-metadata';

// ❌ 피하기: zod 스키마 직접 사용 (빌드 시 타입 추론 오류 가능)
import { aiUsedSchema } from '@apot-platforms/iot-metadata';
type AIUsed = z.infer<typeof aiUsedSchema>; // 타입 추론 오류 발생 가능

이전 버전의 타입이 필요한 경우:

// 버전별 타입에 접근하기
import type { 
  NFTMetadataV1,
  NFTMetadataV2,
  NFTMetadataV3
} from '@apot-platforms/iot-metadata';

// V1 타입 사용
const v1Metadata: NFTMetadataV1 = {
  // ...
};

중요: 내부 경로 직접 참조 금지

아래와 같은 방식으로 직접 내부 폴더 구조를 참조하지 마세요:

// ❌ 잘못된 사용법 - 내부 경로를 직접 참조
import { aiUsedSchema } from '@apot-platforms/iot-metadata/dist/validators/v1';

대신 네임스페이스 또는 직접 export된 항목을 사용하세요:

// ✅ 올바른 사용법 - V1 네임스페이스 사용
import { V1 } from '@apot-platforms/iot-metadata';
const { aiUsedSchema } = V1;

라이선스

ISC