WebXR-JP/xrift-skills

XRift SDK 가이드

@xrift/sdk를 사용하여 XRift 플랫폼 API와 프로그래매틱하게 상호작용하기 위한 가이드입니다.

참고 자료

• API 참조 - XriftClient, WorldsApi, ItemsApi, 오류 클래스 및 유틸리티 함수의 전체 명세
• 코드 템플릿 - Node.js 및 브라우저 환경에서 바로 사용할 수 있는 코드 예제
• 타입 정의 - 모든 SDK 인터페이스에 대한 완전한 TypeScript 타입 정의

주요 규칙

1. API 토큰은 항상 필요함 — XriftClient는 유효한 token으로 초기화되어야 합니다. 토큰을 하드코딩하지 말고 환경 변수나 안전한 구성을 사용하세요.
2. 파일 데이터는 FileData 타입이어야 함 — SDK는 파일 경로나 문자열이 아닌 ArrayBuffer | Uint8Array를 받습니다. 호출자는 파일을 읽어 바이너리 데이터로 만든 후 SDK에 전달해야 합니다.
3. remotePath는 상대 경로여야 함 — 절대 경로나 /로 시작하는 경로를 사용하지 마세요. scene.glb 또는 assets/texture.png와 같은 경로를 사용하세요.
4. 항상 오류를 처리하세요 — API 호출을 try/catch로 감싸고 XriftAuthError, XriftApiError, XriftNetworkError를 별도로 처리하세요.

프로젝트 개요

@xrift/sdk란?

@xrift/sdk는 XRift 플랫폼을 위한 범용 TypeScript SDK입니다. 파일 업로드 기능이 통합된 월드 및 아이템 API에 프로그래매틱하게 접근할 수 있습니다.

주요 특징

• 범용: Node.js (>=18) 및 브라우저 환경에서 모두 사용 가능
• 제로 의존성: 기본 fetch API 기반
• TypeScript 우선: 전체 타입 정의 포함
• 이중 빌드: ESM + CJS 지원
• 통합 업로드: 해시 계산 → 서명된 URL 획득 → 업로드 → 완료를 한 번의 호출로 처리

기술 스택

• TypeScript (strict 모드)
• fetch API (axios 사용 안 함)
• SHA-256 해싱 (node:crypto / Web Crypto API)
• ESM + CJS 이중 빌드

설치

npm install @xrift/sdk

빠른 시작

import { XriftClient, getMimeType } from '@xrift/sdk';

const client = new XriftClient({
  token: process.env.XRIFT_TOKEN!,
});

// 월드 업로드
const result = await client.worlds.upload(
  [
    {
      remotePath: 'scene.glb',
      data: fileData, // Uint8Array 또는 ArrayBuffer
      size: fileData.byteLength,
      contentType: getMimeType('scene.glb'),
    },
  ],
  {
    name: 'My World',
  },
);

console.log(`업로드 완료: ${result.worldId} v${result.versionNumber}`);

업로드 흐름

upload() 메서드(WorldsApi 및 ItemsApi 모두)는 내부적으로 다음 단계를 실행합니다:

1. ID 결정 — 제공된 worldId/itemId를 사용하거나 create()로 새 리소스를 생성
2. 콘텐츠 해시 계산 — 모든 파일 데이터 + 설정 값의 SHA-256 해시 (처음 12자리 16진수)
3. 전체 파일 크기 계산 — 모든 file.size 값의 합계
4. 서명된 업로드 URL 획득 — 메타데이터 및 파일 목록과 함께 /upload-urls 엔드포인트로 POST 요청
5. 파일 업로드 — 각 파일을 올바른 Content-Type 헤더와 함께 서명된 URL로 PUT 요청
6. 업로드 완료 — 버전 ID와 함께 /complete 엔드포인트로 POST 요청

이 모든 단계는 upload()에 의해 내부적으로 처리되며 개별적으로 호출할 수 없습니다.

오류 처리

import { XriftAuthError, XriftApiError, XriftNetworkError } from '@xrift/sdk';

try {
  await client.worlds.upload(files, options);
} catch (error) {
  if (error instanceof XriftAuthError) {
    // 401 - 유효하지 않거나 만료된 토큰
  } else if (error instanceof XriftApiError) {
    // 기타 API 오류 (400, 403, 404, 500 등)
    console.error(`상태: ${error.statusCode}, 본문:`, error.responseBody);
  } else if (error instanceof XriftNetworkError) {
    // 네트워크 연결 문제
    console.error('원인:', error.cause);
  }
}

오류 계층 구조

XriftSdkError (기본)
├── XriftApiError (HTTP 오류, statusCode 및 responseBody 포함)
│   └── XriftAuthError (HTTP 401)
└── XriftNetworkError (연결 오류, cause 포함)

Node.js vs 브라우저

항목	Node.js	브라우저
파일 읽기	fs.readFile() → Uint8Array	File.arrayBuffer() → Uint8Array
해시 알고리즘	node:crypto (createHash)	crypto.subtle.digest (Web Crypto API)
토큰 저장	환경 변수	안전한 저장소 (localStorage 사용 금지)
최소 버전	Node.js 18+	fetch + Web Crypto를 지원하는 최신 브라우저

관련 리소스

• npm: @xrift/sdk
• GitHub: WebXR-JP/xrift-sdk
• XRift 문서