Rozod NPM | npm.io

About

RoZod makes working with Roblox APIs simple and type-safe in TypeScript. With just a few lines of code, you can fetch data from both traditional Roblox web APIs and the newer OpenCloud APIs with full type safety.

Features

✨ Simple Interface - Easy to understand API with minimal boilerplate
🔒 Type Safety - Complete TypeScript type safety for requests and responses
📚 Comprehensive API Coverage - Access to both traditional Roblox web APIs and OpenCloud APIs
🔄 Pagination Helpers - Easy tools for handling paginated responses
🔁 Batch Processing - Split large requests automatically to avoid API limits
🔍 Custom Endpoints - Define your own endpoints with full type safety

Installation

npm install rozod
# or
yarn add rozod
# or
pnpm add rozod

Quick Start

import { fetchApi } from 'rozod';
import { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';

// Fetch user details with full type safety
const userInfo = await fetchApi(getUsersUserdetails, { userIds: [1, 123456] });
console.log(userInfo.data[0].displayName); // Properly typed!

Usage

Fetch a Single Request

import { fetchApi } from 'rozod';
import { getGamesIcons } from 'rozod/lib/endpoints/gamesv1';

const response = await fetchApi(getGamesIcons, { universeIds: [1534453623, 65241] });
console.log(response.data);

Handle Paginated Responses

import { fetchApiPages } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

// Automatically fetches all pages
const allPosts = await fetchApiPages(getGroupsGroupidWallPosts, { groupId: 11479637 });
console.log(`Found ${allPosts.length} wall posts`);

Process Pages One at a Time

import { fetchApiPagesGenerator } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

// Process pages as they arrive
const pages = fetchApiPagesGenerator(getGroupsGroupidWallPosts, { groupId: 11479637 });
for await (const page of pages) {
    console.log(`Processing page with ${page.data.length} posts`);
    // Do something with this page
}

Batch Processing Large Requests

import { fetchApiSplit } from 'rozod';
import { getGamesIcons } from 'rozod/lib/endpoints/gamesv1';

// Will automatically split into smaller batches of 100 universeIds per request
const data = await fetchApiSplit(
    getGamesIcons, 
    { universeIds: [1, 2, 3, 4, 5, /* many more IDs */] }, 
    { universeIds: 100 }
);
console.log(data);

OpenCloud

RoZod supports Roblox's newer OpenCloud APIs with the same easy interface:

import { fetchApi } from 'rozod';
import { v2 } from 'rozod/lib/opencloud';

// Get universe details through OpenCloud
const universeInfo = await fetchApi(v2.getCloudV2UniversesUniverseId, { 
    universe_id: '123456789'
});

// Access typed properties
console.log(universeInfo.displayName);
console.log(universeInfo.description);

Access DataStores via OpenCloud

import { fetchApi } from 'rozod';
import { getCloudV2UniversesUniverseIdDataStoresDataStoreIdEntries } from 'rozod/lib/opencloud/v2/cloud';

// Get DataStore entries with type safety
const dataStoreEntries = await fetchApi(
    getCloudV2UniversesUniverseIdDataStoresDataStoreIdEntries, 
    {
        universe_id: '123456789',
        data_store_id: 'MyStore'
    }
);

Custom Endpoints

You can define custom endpoints for your specific needs:

import { z } from 'zod';
import { endpoint, fetchApi } from 'rozod';

const myCustomEndpoint = endpoint({
  method: 'GET',
  path: '/v1/custom/:customId',
  baseUrl: 'https://my-api.example.com',
  parameters: {
    customId: z.string(),
    optional: z.string().optional()
  },
  response: z.object({
    success: z.boolean(),
    data: z.array(z.string())
  }),
});

const response = await fetchApi(myCustomEndpoint, { customId: '123' });