XRift-JP/xrift-skills

Guia do SDK XRift

Um guia para usar @xrift/sdk e interagir programaticamente com a API da plataforma XRift.

Referências

• Referência da API - Especificação completa de XriftClient, WorldsApi, ItemsApi, classes de erro e funções utilitárias
• Modelos de Código - Exemplos de código prontos para uso em ambientes Node.js e navegador
• Definições de Tipo - Definições de tipo TypeScript completas para todas as interfaces do SDK

Regras Críticas

1. O token da API é sempre obrigatório — XriftClient deve ser inicializado com um token válido. Nunca codifique tokens diretamente no código; use variáveis de ambiente ou configuração segura.
2. Os dados do arquivo devem ser do tipo FileData — O SDK aceita ArrayBuffer | Uint8Array, não caminhos de arquivo ou strings. O chamador é responsável por ler os arquivos em dados binários antes de passá-los ao SDK.
3. remotePath deve ser um caminho relativo — Nunca use caminhos absolutos ou caminhos que começam com /. Use caminhos como scene.glb ou assets/texture.png.
4. Sempre trate os erros — Envolva as chamadas da API em try/catch e trate XriftAuthError, XriftApiError e XriftNetworkError separadamente.

Visão Geral do Projeto

O que é @xrift/sdk?

@xrift/sdk é um SDK TypeScript universal para a plataforma XRift. Ele fornece acesso programático às APIs de mundos e itens com capacidades integradas de upload de arquivos.

Características Principais

• Universal: Funciona tanto em ambientes Node.js (>=18) quanto em navegadores
• Zero dependências: Construído na API nativa fetch
• TypeScript em primeiro lugar: Definições de tipo completas incluídas
• Build dupla: Suporte ESM + CJS
• Upload integrado: Cálculo de hash → obtenção de URL assinada → upload → conclusão em uma única chamada

Stack Tecnológica

• TypeScript (modo estrito)
• API fetch (sem axios)
• Hash SHA-256 (node:crypto / Web Crypto API)
• Build dupla ESM + CJS

Instalação

npm install @xrift/sdk

Início Rápido

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

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

// Enviar um mundo
const result = await client.worlds.upload(
  [
    {
      remotePath: 'scene.glb',
      data: fileData, // Uint8Array ou ArrayBuffer
      size: fileData.byteLength,
      contentType: getMimeType('scene.glb'),
    },
  ],
  {
    name: 'Meu Mundo',
  },
);

console.log(`Upload concluído: ${result.worldId} v${result.versionNumber}`);

Fluxo de Upload

O método upload() (tanto em WorldsApi quanto em ItemsApi) executa estas etapas internamente:

1. Determinar ID — Usar o worldId/itemId fornecido ou criar um novo recurso via create()
2. Calcular hash de conteúdo — Hash SHA-256 de todos os dados do arquivo + valores de configuração (primeiros 12 caracteres hexadecimais)
3. Calcular tamanho total do arquivo — Soma de todos os valores file.size
4. Obter URLs de upload assinadas — POST para o endpoint /upload-urls com metadados e lista de arquivos
5. Enviar arquivos — PUT de cada arquivo para sua URL assinada com o cabeçalho Content-Type correto
6. Concluir upload — POST para o endpoint /complete com o ID da versão

Todas essas etapas são tratadas internamente por upload() e não podem ser chamadas individualmente.

Tratamento de Erros

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

try {
  await client.worlds.upload(files, options);
} catch (error) {
  if (error instanceof XriftAuthError) {
    // 401 - Token inválido ou expirado
  } else if (error instanceof XriftApiError) {
    // Outros erros da API (400, 403, 404, 500, etc.)
    console.error(`Status: ${error.statusCode}, Corpo:`, error.responseBody);
  } else if (error instanceof XriftNetworkError) {
    // Problemas de conectividade de rede
    console.error('Causa:', error.cause);
  }
}

Hierarquia de Erros

XriftSdkError (base)
├── XriftApiError (erros HTTP com statusCode e responseBody)
│   └── XriftAuthError (HTTP 401)
└── XriftNetworkError (erros de conectividade com cause)

Node.js vs Navegador

Aspecto	Node.js	Navegador
Leitura de arquivos	fs.readFile() → Uint8Array	File.arrayBuffer() → Uint8Array
Algoritmo de hash	node:crypto (createHash)	crypto.subtle.digest (Web Crypto API)
Armazenamento de token	Variáveis de ambiente	Armazenamento seguro (não localStorage)
Versão mínima	Node.js 18+	Navegadores modernos com fetch + Web Crypto

Recursos Relacionados

• npm: @xrift/sdk
• GitHub: WebXR-JP/xrift-sdk
• Documentação XRift