rozod 6.7.1 → 6.8.0

package/LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2025 Alrovi ApS
+Copyright (c) 2026 Alrovi ApS
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

package/README.md

@@ -1,451 +1,75 @@
-<h1 align="center" style="height: 200; overflow: 'hidden'">
-    <img src="https://github.com/alexop1000/RoZod/assets/46445843/1c2a6cb5-b1d6-4784-b084-0679d81109c3" alt="RoZod" width="400" />
-    <br>
-</h1>
-
-<h4 align="center">Type-safe Roblox API and OpenCloud client for TypeScript</h4>
-
-<p align="center">
-    <a href="https://www.npmjs.com/package/rozod"><img alt="npm bundle size" src="https://img.shields.io/bundlephobia/min/rozod?style=for-the-badge"></a>
-    <a href="https://www.npmjs.com/package/rozod"><img alt="npm" src="https://img.shields.io/npm/v/rozod?style=for-the-badge"></a>
-    <a href="https://www.npmjs.com/package/rozod"><img alt="npm" src="https://img.shields.io/npm/dt/rozod?style=for-the-badge"></a>
-</p>
-<p align="center">
-  <a href="#about">About</a> •
-  <a href="#features">Features</a> •
-  <a href="#installation">Installation</a> •
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#usage">Usage</a> •
-  <a href="#opencloud">OpenCloud</a> •
-  <a href="#credits">Credits</a> •
-  <a href="http://rozod.alrovi.com">Documentation</a>
-</p>
-
----
-
-## About
-
-`RoZod` makes working with Roblox APIs simple and type-safe in TypeScript. With **695+ classic Roblox web API endpoints** and **115+ OpenCloud endpoints** (all code-generated from official Roblox documentation), you get comprehensive coverage of virtually every available Roblox API with full type safety.
-
-Perfect for everything from small one-time NodeJS/Bun/Deno scripts to large-scale production applications. RoZod powers [RoGold](https://rogold.live), a browser extension with **800,000+ active users**, handling millions of API requests daily across both frontend extensions and backend workflows.
-
-## Features
-
-- ✨ **Simple Interface** - Easy to understand API with minimal boilerplate
-- 🔒 **Type Safety** - Complete TypeScript type safety for requests and responses
-- 📚 **810+ Total Endpoints** - 695+ classic web APIs + 115+ OpenCloud APIs, all code-generated from official docs
-- 🚀 **Production Ready** - Battle-tested in applications serving 800,000+ users
-- 🔄 **Pagination Helpers** - Easy tools for handling paginated responses
-- 🔁 **Batch Processing** - Split large requests automatically to avoid API limits
-- 🌐 **Universal Runtime Support** - Works seamlessly in NodeJS, Bun, Deno, and browsers
-- 🔍 **Custom Endpoints** - Define your own endpoints with full type safety
-- 🧩 **Smart Error Handling** - Choose between safe unions or throw-on-error
-
-## Installation
-
-```bash
-npm install rozod
-# or
-bun add rozod
-# or
-yarn add rozod
-# or
-pnpm add rozod
-```
-
-## Quick Start
-
-```ts
-import { fetchApi, isAnyErrorResponse } from 'rozod';
-import { getUsersUserid } from 'rozod/endpoints/usersv1';
-
-// Fetch user details with full type safety
-const userInfo = await fetchApi(getUsersUserid, { userId: 1 });
-if (isAnyErrorResponse(userInfo)) {
-  return;
-}
-console.log(userInfo.displayName); // Properly typed!
-```
-
-## Usage
-
-### Fetch a Single Request
-
-```ts
-import { fetchApi, isAnyErrorResponse } from 'rozod';
-import { getGamesIcons } from 'rozod/endpoints/thumbnailsv1';
-
-const response = await fetchApi(getGamesIcons, { universeIds: [1534453623, 65241] });
-if (!isAnyErrorResponse(response)) {
-  console.log(response.data);
-}
-```
-
-### Handle Paginated Responses
-
-```ts
-import { fetchApiPages, isAnyErrorResponse } from 'rozod';
-import { getGroupsGroupidWallPosts } from 'rozod/endpoints/groupsv2';
-
-// Automatically fetches all pages
-const pages = await fetchApiPages(getGroupsGroupidWallPosts, { groupId: 11479637 });
-if (!isAnyErrorResponse(pages)) {
-  console.log(`Fetched ${pages.length} pages of wall posts`);
-}
-```
-
-### Process Pages One at a Time
-
-```ts
-import { fetchApiPagesGenerator, isAnyErrorResponse } from 'rozod';
-import { getGroupsGroupidWallPosts } from 'rozod/endpoints/groupsv2';
-
-// Process pages as they arrive
-const pages = fetchApiPagesGenerator(getGroupsGroupidWallPosts, { groupId: 11479637 });
-for await (const page of pages) {
-  if (isAnyErrorResponse(page)) break;
-  console.log(`Processing page with ${page.data.length} posts`);
-  // Do something with this page
-}
-```
-
-### Batch Processing Large Requests
-
-```ts
-import { fetchApiSplit } from 'rozod';
-import { getGamesIcons } from 'rozod/endpoints/thumbnailsv1';
-
-// 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);
-```
-
-### Handling Errors
-
-By default, requests return either the success type or a simple `AnyError`. Use the tiny helper to check:
-
-```ts
-import { fetchApi, isAnyErrorResponse } from 'rozod';
-import { getGamesIcons } from 'rozod/endpoints/thumbnailsv1';
-
-const res = await fetchApi(getGamesIcons, { universeIds: [1534453623] });
-if (isAnyErrorResponse(res)) {
-  console.error(res.message);
-} else {
-  console.log(res.data);
-}
-```
-
-Prefer a straight try/catch? Enable throwing:
-
-```ts
-try {
-  const res = await fetchApi(getGamesIcons, { universeIds: [1534453623] }, { throwOnError: true });
-  console.log(res.data);
-} catch (err) {
-  console.error((err as Error).message);
-}
-```
-
-Need the raw Response? Use `returnRaw: true`:
-
-```ts
-const resp = await fetchApi(getGamesIcons, { universeIds: [1534453623] }, { returnRaw: true });
-const json = await resp.json();
-```
-
-## OpenCloud
-
-RoZod supports Roblox's newer OpenCloud APIs with the same easy interface:
-
-```ts
-import { fetchApi, isAnyErrorResponse } from 'rozod';
-import { v2 } from 'rozod/opencloud';
-
-// Get universe details through OpenCloud
-const universeInfo = await fetchApi(v2.getCloudV2UniversesUniverseId, {
-  universe_id: '123456789',
-});
-
-if (!isAnyErrorResponse(universeInfo)) {
-  // Access typed properties
-  console.log(universeInfo.displayName);
-  console.log(universeInfo.description);
-}
-```
-
-### Access DataStores via OpenCloud
-
-```ts
-import { fetchApi } from 'rozod';
-import { getCloudV2UniversesUniverseIdDataStoresDataStoreIdEntries } from 'rozod/opencloud/v2/cloud';
-
-// Get DataStore entries with type safety
-const dataStoreEntries = await fetchApi(getCloudV2UniversesUniverseIdDataStoresDataStoreIdEntries, {
-  universe_id: '123456789',
-  data_store_id: 'MyStore',
-});
-```
-
-## Authentication
-
-RoZod handles Roblox authentication automatically with comprehensive security features:
-
-### Browser Environments
-
-In browsers, authentication works automatically when users are logged into Roblox:
-
-```ts
-import { fetchApi } from 'rozod';
-import { getUsersUserid } from 'rozod/endpoints/usersv1';
-
-// Cookies are sent automatically - no setup required!
-const userInfo = await fetchApi(getUsersUserid, { userId: 123456 });
-```
-
-### Server Environments (Node.js/Bun/Deno)
-
-For server environments, use `configureServer()` to set up authentication once:
-
-```ts
-import { configureServer, fetchApi } from 'rozod';
-import { getUsersUserid } from 'rozod/endpoints/usersv1';
-
-// Configure once at startup
-configureServer({ cookies: 'your_roblosecurity_cookie_here' });
-
-// All subsequent requests automatically include the cookie
-const userInfo = await fetchApi(getUsersUserid, { userId: 123456 });
-```
-
-#### Multiple Accounts (Cookie Pool)
-
-Use multiple Roblox accounts for load distribution or fallback:
-
-```ts
-import { configureServer } from 'rozod';
-
-// Multiple accounts with round-robin rotation (default)
-configureServer({
-  cookies: [
-    'account1_roblosecurity_cookie',
-    'account2_roblosecurity_cookie',
-    'account3_roblosecurity_cookie',
-  ],
-});
-
-// Requests automatically cycle through accounts: 1 → 2 → 3 → 1 → 2 → ...
-```
-
-#### Rotation Modes
-
-Control how cookies and user agents are selected:
-
-```ts
-import { configureServer } from 'rozod';
-
-configureServer({
-  cookies: ['cookie1', 'cookie2', 'cookie3'],
-  cookieRotation: 'round-robin',  // Cycle sequentially (default for multiple)
-  // cookieRotation: 'random',    // Pick randomly per request
-  // cookieRotation: 'none',      // Always use first cookie
-
-  userAgents: ['CustomBot/1.0', 'CustomBot/2.0'],  // Optional custom UAs
-  userAgentRotation: 'none',      // Consistent per session (default)
-  // userAgentRotation: 'random',
-  // userAgentRotation: 'round-robin',
-});
-```
-
-#### User Agent Pool
-
-RoZod includes built-in browser user agents applied automatically in server environments. Customize or disable:
-
-```ts
-// Use custom user agents
-configureServer({
-  cookies: '...',
-  userAgents: ['MyBot/1.0', 'MyService/2.0'],
-  userAgentRotation: 'round-robin',
-});
-
-// Disable user agent injection
-configureServer({ cookies: '...', userAgents: [] });
-```
-
-#### OpenCloud API Key
-
-For OpenCloud endpoints (`apis.roblox.com`), set your API key once:
-
-```ts
-import { configureServer, fetchApi } from 'rozod';
-import { v2 } from 'rozod/opencloud';
-
-// Configure OpenCloud API key
-configureServer({ cloudKey: 'your_opencloud_api_key_here' });
-
-// All OpenCloud requests automatically include x-api-key header
-const universeInfo = await fetchApi(v2.getCloudV2UniversesUniverseId, {
-  universe_id: '123456789',
-});
-```
-
-You can configure both classic API cookies and OpenCloud keys together:
-
-```ts
-configureServer({
-  cookies: ['account1', 'account2'],  // For classic *.roblox.com APIs
-  cloudKey: 'your_opencloud_key',     // For apis.roblox.com
-});
-```
-
-> **Note:** The API key is only applied to OpenCloud endpoints (URLs containing `/cloud/`). Cookies are applied to all other Roblox APIs, including undocumented cookie-based APIs on `apis.roblox.com`.
-
-#### Configuration Management
-
-```ts
-import { configureServer, clearServerConfig, getServerConfig } from 'rozod';
-
-// Check current configuration
-const config = getServerConfig();
-console.log(config.cookies, config.cloudKey);
-
-// Clear all server configuration
-clearServerConfig();
-```
-
-#### Manual Headers (Legacy)
-
-You can still pass headers manually per-request if needed:
-
-```ts
-const userInfo = await fetchApi(
-  getUsersUserid, 
-  { userId: 123456 },
-  {
-    headers: {
-      'Cookie': '.ROBLOSECURITY=your_cookie_here'
-    }
-  }
-);
-```
-
-> **Note:** Manual headers take precedence over `configureServer()` defaults.
-
-### Security Features
-
-RoZod automatically handles advanced Roblox security requirements:
-
-- **✅ XCSRF Token Management** - Automatic CSRF token retrieval and caching
-- **✅ Hardware-Backed Authentication** - Full HBA signature support  
-- **✅ Challenge Handling** - Captchas, 2FA, and other authentication challenges
-- **✅ Cookie Security** - Secure cookie parsing and validation
-- **✅ Cookie Rotation** - Automatic handling of Roblox's cookie rotation
-
-### Cookie Rotation Handling
-
-Roblox is gradually implementing `.ROBLOSECURITY` cookie rotation for improved security. RoZod automatically detects when cookies are rotated and can notify you to persist the new values:
-
-```ts
-import { configureServer, refreshCookie, getCookies } from 'rozod';
-
-configureServer({
-  cookies: process.env.ROBLOX_COOKIE,
-  onCookieRefresh: async ({ oldCookie, newCookie, poolIndex }) => {
-    // Roblox rotated the cookie - persist the new value
-    await db.updateCookie(poolIndex, newCookie);
-    console.log('Cookie rotated and saved!');
-  }
-});
-```
-
-The internal cookie pool updates automatically, so the callback is only needed if you want to persist cookies across restarts.
-
-You can also proactively refresh cookies before they expire:
-
-```ts
-// Refresh on a schedule or before important operations
-const result = await refreshCookie(0);
-if (result.success) {
-  await db.updateCookie(0, result.newCookie);
-}
-
-// Utility functions
-const allCookies = getCookies();        // Get current cookie values
-updateCookie(0, 'new_value');           // Manually update a cookie
-```
-
-### Challenge Handling
-
-For advanced authentication challenges (captchas, 2FA), set up a global challenge handler:
-
-```ts
-import { setHandleGenericChallenge } from 'rozod';
-
-setHandleGenericChallenge(async (challenge) => {
-  // Handle captcha, 2FA, or other challenges
-  // Return the challenge response or undefined to skip
-  if (challenge.challengeType === 'captcha') {
-    const solution = await solveCaptcha(challenge.challengeId);
-    return {
-      challengeType: challenge.challengeType,
-      challengeId: challenge.challengeId,
-      challengeBase64Metadata: solution
-    };
-  }
-});
-```
-
-### Hardware-Backed Authentication (Advanced)
-
-For Node.js environments requiring custom HBA keys:
-
-```ts
-import { changeHBAKeys } from 'rozod';
-
-// Provide your own crypto key pair for HBA signatures
-const keyPair = await crypto.subtle.generateKey(
-  { name: 'ECDSA', namedCurve: 'P-256' },
-  true,
-  ['sign', 'verify']
-);
-
-changeHBAKeys(keyPair);
-```
-
-## Custom Endpoints
-
-You can define custom endpoints for your specific needs:
-
-```ts
-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' });
-```
-
-## Credits
-
-This repository is maintained by Alrovi ApS, the company behind RoGold.
-
-## Disclaimer
-
-RoZod is not affiliated with, maintained, authorized, endorsed, or sponsored by Roblox Corporation or any of its affiliates.
+<h1 align="center" style="height: 200; overflow: 'hidden'">
+    <img src="https://github.com/alexop1000/RoZod/assets/46445843/1c2a6cb5-b1d6-4784-b084-0679d81109c3" alt="RoZod" width="400" />
+    <br>
+</h1>
+
+<h4 align="center">Type-safe Roblox API and OpenCloud client for TypeScript</h4>
+
+<p align="center">
+    <a href="https://www.npmjs.com/package/rozod"><img alt="npm bundle size" src="https://img.shields.io/bundlephobia/min/rozod?style=for-the-badge"></a>
+    <a href="https://www.npmjs.com/package/rozod"><img alt="npm" src="https://img.shields.io/npm/v/rozod?style=for-the-badge"></a>
+    <a href="https://www.npmjs.com/package/rozod"><img alt="npm" src="https://img.shields.io/npm/dt/rozod?style=for-the-badge"></a>
+</p>
+
+<p align="center">
+  <a href="https://rozod.alrovi.com">Documentation</a> •
+  <a href="https://rozod.alrovi.com/getting-started/quick-start/">Quick Start</a> •
+  <a href="https://rozod.alrovi.com/reference/core-api/">API Reference</a>
+</p>
+
+---
+
+RoZod makes working with Roblox APIs simple and type-safe. **695+ classic web API endpoints** and **115+ OpenCloud endpoints**, all code-generated from official Roblox documentation, with authentication, CSRF tokens, cookie rotation, pagination, batching, and error parsing handled for you.
+
+Works in Node.js, Bun, Deno, browsers, and browser extensions. Battle-tested in [RoGold](https://rogold.live), serving 800,000+ users with millions of API requests daily.
+
+## Installation
+
+```bash
+npm install rozod
+```
+
+## Quick Start
+
+```ts
+import { fetchApi, isAnyErrorResponse } from 'rozod';
+import { getUsersUserid } from 'rozod/endpoints/usersv1';
+
+const user = await fetchApi(getUsersUserid, { userId: 1 });
+if (!isAnyErrorResponse(user)) {
+  console.log(user.displayName); // fully typed!
+}
+```
+
+On a server, configure authentication once and every request uses it:
+
+```ts
+import { configureServer } from 'rozod';
+
+configureServer({
+  cookies: process.env.ROBLOX_COOKIE,   // classic *.roblox.com APIs
+  cloudKey: process.env.ROBLOX_CLOUD_KEY, // OpenCloud APIs
+});
+```
+
+## Documentation
+
+Full guides and reference at **[rozod.alrovi.com](https://rozod.alrovi.com)**:
+
+- [Installation & Setup](https://rozod.alrovi.com/getting-started/installation/)
+- [Authentication](https://rozod.alrovi.com/guides/authentication/) — cookie pools, rotation, OpenCloud keys, challenges
+- [Error Handling](https://rozod.alrovi.com/guides/error-handling/)
+- [Pagination](https://rozod.alrovi.com/guides/pagination/) & [Batch Requests](https://rozod.alrovi.com/guides/batch-requests/)
+- [Caching](https://rozod.alrovi.com/guides/caching/)
+- [OpenCloud](https://rozod.alrovi.com/guides/opencloud/) & [Long-Running Operations](https://rozod.alrovi.com/guides/long-running-operations/)
+- [Custom Endpoints](https://rozod.alrovi.com/guides/custom-endpoints/)
+- [Core API Reference](https://rozod.alrovi.com/reference/core-api/) — every exported function and type
+- [Coming from noblox.js?](https://rozod.alrovi.com/getting-started/migration-from-nobloxjs/)
+
+## Credits
+
+Maintained by Alrovi ApS, the company behind RoGold.
+
+## Disclaimer
+
+RoZod is not affiliated with, maintained, authorized, endorsed, or sponsored by Roblox Corporation or any of its affiliates.