XRift SDK Skill

XRift SDK Leitfaden

Ein Leitfaden zur Verwendung von @xrift/sdk für die programmatische Interaktion mit der XRift-Plattform-API.

Referenzen

• API-Referenz – Vollständige Spezifikation von XriftClient, WorldsApi, ItemsApi, Fehlerklassen und Hilfsfunktionen
• Code-Vorlagen – Fertige Codebeispiele für Node.js- und Browser-Umgebungen
• Typdefinitionen – Vollständige TypeScript-Typdefinitionen für alle SDK-Schnittstellen

Wichtige Regeln

1. API-Token ist immer erforderlich – XriftClient muss mit einem gültigen token initialisiert werden. Tokens niemals hartcodieren; verwenden Sie Umgebungsvariablen oder eine sichere Konfiguration.
2. Dateidaten müssen vom Typ FileData sein – Das SDK akzeptiert ArrayBuffer | Uint8Array, keine Dateipfade oder Zeichenfolgen. Der Aufrufer ist dafür verantwortlich, Dateien vor der Übergabe an das SDK in Binärdaten einzulesen.
3. remotePath muss ein relativer Pfad sein – Verwenden Sie niemals absolute Pfade oder Pfade, die mit / beginnen. Verwenden Sie Pfade wie scene.glb oder assets/texture.png.
4. Fehler immer behandeln – API-Aufrufe in try/catch-Blöcke einschließen und XriftAuthError, XriftApiError und XriftNetworkError separat behandeln.

Projektübersicht

Was ist @xrift/sdk?

@xrift/sdk ist ein universelles TypeScript-SDK für die XRift-Plattform. Es bietet programmatischen Zugriff auf die APIs für Welten und Objekte mit integrierten Datei-Upload-Funktionen.

Hauptmerkmale

• Universell: Funktioniert sowohl in Node.js (>=18) als auch in Browser-Umgebungen
• Keine Abhängigkeiten: Basiert auf der nativen fetch-API
• TypeScript zuerst: Vollständige Typdefinitionen enthalten
• Dualer Build: Unterstützung für ESM + CJS
• Integrierter Upload: Hash-Berechnung → Signierte URL abrufen → Hochladen → Abschluss in einem Aufruf

Technologie-Stack

• TypeScript (strenger Modus)
• fetch-API (kein axios)
• SHA-256-Hashing (node:crypto / Web Crypto API)
• ESM + CJS Dualer Build

Installation

npm install @xrift/sdk

Schnellstart

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

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

// Eine Welt hochladen
const result = await client.worlds.upload(
  [
    {
      remotePath: 'scene.glb',
      data: fileData, // Uint8Array oder ArrayBuffer
      size: fileData.byteLength,
      contentType: getMimeType('scene.glb'),
    },
  ],
  {
    name: 'Meine Welt',
  },
);

console.log(`Hochgeladen: ${result.worldId} v${result.versionNumber}`);

Upload-Ablauf

Die upload()-Methode (sowohl auf WorldsApi als auch ItemsApi) führt intern diese Schritte aus:

1. ID ermitteln – Verwendet die bereitgestellte worldId/itemId oder erstellt eine neue Ressource mittels create()
2. Content-Hash berechnen – SHA-256-Hash aller Dateidaten + Konfigurationswerte (erste 12 hexadezimale Zeichen)
3. Gesamtdateigröße berechnen – Summe aller file.size-Werte
4. Signierte Upload-URLs abrufen – POST an den /upload-urls-Endpunkt mit Metadaten und Dateiliste
5. Dateien hochladen – PUT jeder Datei an ihre signierte URL mit dem korrekten Content-Type-Header
6. Upload abschließen – POST an den /complete-Endpunkt mit der Versions-ID

All diese Schritte werden intern von upload() behandelt und können nicht einzeln aufgerufen werden.

Fehlerbehandlung

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

try {
  await client.worlds.upload(files, options);
} catch (error) {
  if (error instanceof XriftAuthError) {
    // 401 – Ungültiges oder abgelaufenes Token
  } else if (error instanceof XriftApiError) {
    // Andere API-Fehler (400, 403, 404, 500 usw.)
    console.error(`Status: ${error.statusCode}, Body:`, error.responseBody);
  } else if (error instanceof XriftNetworkError) {
    // Netzwerkverbindungsprobleme
    console.error('Ursache:', error.cause);
  }
}

Fehlerhierarchie

XriftSdkError (Basis)
├── XriftApiError (HTTP-Fehler mit statusCode und responseBody)
│   └── XriftAuthError (HTTP 401)
└── XriftNetworkError (Verbindungsfehler mit cause)

Node.js vs. Browser

Aspekt	Node.js	Browser
Datei lesen	fs.readFile() → Uint8Array	File.arrayBuffer() → Uint8Array
Hash-Algorithmus	node:crypto (createHash)	crypto.subtle.digest (Web Crypto API)
Token-Speicherung	Umgebungsvariablen	Sicherer Speicher (nicht localStorage)
Mindestversion	Node.js 18+	Moderne Browser mit fetch + Web Crypto

Verwandte Ressourcen

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