rozod 6.0.0 → 6.1.0

package/README.md

@@ -6,7 +6,7 @@
 <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/minzip/rozod?style=for-the-badge"></a>
+    <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>
@@ -24,16 +24,22 @@
 ---
 
 ## 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.
+
+`RoZod` makes working with Roblox APIs simple and type-safe in TypeScript. With **650+ classic Roblox web API endpoints** and **95+ 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
-- 📚 **Comprehensive API Coverage** - Access to both traditional Roblox web APIs and OpenCloud APIs
+- 📚 **750+ Total Endpoints** - 650+ classic web APIs + 95+ 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
 
@@ -53,6 +59,9 @@ import { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';
 
 // Fetch user details with full type safety
 const userInfo = await fetchApi(getUsersUserdetails, { userIds: [1, 123456] });
+if (isAnyErrorResponse(userInfo)) {
+  return;
+}
 console.log(userInfo.data[0].displayName); // Properly typed!
 ```
 
@@ -88,8 +97,8 @@ 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
+  console.log(`Processing page with ${page.data.length} posts`);
+  // Do something with this page
 }
 ```
 
@@ -101,13 +110,47 @@ 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 }
+  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/lib/endpoints/gamesv1';
+
+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:
@@ -117,8 +160,8 @@ import { fetchApi } from 'rozod';
 import { v2 } from 'rozod/lib/opencloud';
 
 // Get universe details through OpenCloud
-const universeInfo = await fetchApi(v2.getCloudV2UniversesUniverseId, { 
-    universe_id: '123456789'
+const universeInfo = await fetchApi(v2.getCloudV2UniversesUniverseId, {
+  universe_id: '123456789',
 });
 
 // Access typed properties
@@ -133,12 +176,232 @@ 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'
+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 { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';
+
+// Cookies are sent automatically - no setup required!
+const userInfo = await fetchApi(getUsersUserdetails, { userIds: [123456] });
+```
+
+### Server Environments (Node.js/Bun/Deno)
+
+For server environments, use `configureServer()` to set up authentication once:
+
+```ts
+import { configureServer, fetchApi } from 'rozod';
+import { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';
+
+// Configure once at startup
+configureServer({ cookies: 'your_roblosecurity_cookie_here' });
+
+// All subsequent requests automatically include the cookie
+const userInfo = await fetchApi(getUsersUserdetails, { userIds: [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 } from 'rozod';
+import { v2 } from 'rozod/lib/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(
+  getUsersUserdetails, 
+  { userIds: [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
+
+### 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);
+```
+
+### OpenCloud Authentication
+
+OpenCloud APIs require API keys. Use `configureServer()` for automatic injection:
+
+```ts
+import { configureServer, fetchApi } from 'rozod';
+import { v2 } from 'rozod/lib/opencloud';
+
+// Configure once at startup
+configureServer({ cloudKey: 'your_opencloud_api_key_here' });
+
+// All OpenCloud requests automatically include x-api-key
+const universeInfo = await fetchApi(v2.getCloudV2UniversesUniverseId, {
+  universe_id: '123456789',
+});
+```
+
+Or pass headers manually per-request:
+
+```ts
+const universeInfo = await fetchApi(
+  v2.getCloudV2UniversesUniverseId,
+  { universe_id: '123456789' },
+  {
+    headers: {
+      'x-api-key': 'your_opencloud_api_key_here'
     }
+  }
 );
 ```
 
@@ -156,11 +419,11 @@ const myCustomEndpoint = endpoint({
   baseUrl: 'https://my-api.example.com',
   parameters: {
     customId: z.string(),
-    optional: z.string().optional()
+    optional: z.string().optional(),
   },
   response: z.object({
     success: z.boolean(),
-    data: z.array(z.string())
+    data: z.array(z.string()),
   }),
 });
 
@@ -168,7 +431,9 @@ 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.

package/lib/cache.js

@@ -68,7 +68,17 @@ class ChromeStore {
         return new Promise((resolve) => {
             // @ts-ignore
             chrome?.storage?.local?.get?.(null, (result) => {
-                resolve(result?.filter?.((key) => key.startsWith('rozod_cache:')));
+                if (!result) {
+                    resolve({});
+                    return;
+                }
+                const filtered = {};
+                for (const key of Object.keys(result)) {
+                    if (key.startsWith('rozod_cache:')) {
+                        filtered[key] = result[key];
+                    }
+                }
+                resolve(filtered);
             });
         });
     }

package/lib/endpoints/accountinformationv1.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getXboxLiveConsecutiveLoginDays = exports.getUsersUseridRobloxBadges = exports.getUsersUseridPromotionChannels = exports.deleteStarCodeAffiliates = exports.postStarCodeAffiliates = exports.getStarCodeAffiliates = exports.postPromotionChannels = exports.getPromotionChannels = exports.postPhoneVerify = exports.postPhoneResend = exports.postPhoneDelete = exports.postPhone = exports.getPhone = exports.getMetadata = exports.postGender = exports.getGender = exports.postEmailVerify = exports.postDescription = exports.getDescription = exports.postBirthdate = exports.getBirthdate = void 0;
+exports.getUsersUseridRobloxBadges = exports.getUsersUseridPromotionChannels = exports.deleteStarCodeAffiliates = exports.postStarCodeAffiliates = exports.getStarCodeAffiliates = exports.postPromotionChannels = exports.getPromotionChannels = exports.postPhoneVerify = exports.postPhoneResend = exports.postPhoneDelete = exports.postPhone = exports.getPhone = exports.getMetadata = exports.postGender = exports.getGender = exports.postEmailVerify = exports.postDescription = exports.getDescription = exports.getBirthdate = void 0;
 const zod_1 = require("zod");
 const __1 = require("..");
 const Roblox_AccountInformation_Api_Models_BirthdateResponse = zod_1.z.object({
@@ -8,13 +8,6 @@ const Roblox_AccountInformation_Api_Models_BirthdateResponse = zod_1.z.object({
     birthDay: zod_1.z.number().int(),
     birthYear: zod_1.z.number().int(),
 });
-const Roblox_AccountInformation_Api_Models_BirthdateRequest = zod_1.z.object({
-    birthMonth: zod_1.z.number().int(),
-    birthDay: zod_1.z.number().int(),
-    birthYear: zod_1.z.number().int(),
-    password: zod_1.z.string(),
-});
-const Roblox_Web_WebAPI_ApiEmptyResponseModel = zod_1.z.object({});
 const Roblox_AccountInformation_Api_Models_DescriptionResponse = zod_1.z.object({
     description: zod_1.z.string(),
 });
@@ -27,6 +20,7 @@ const Roblox_AccountInformation_Api_Models_GenderResponse = zod_1.z.object({
 const Roblox_AccountInformation_Api_Models_GenderRequest = zod_1.z.object({
     gender: zod_1.z.string(),
 });
+const Roblox_Web_WebAPI_ApiEmptyResponseModel = zod_1.z.object({});
 const Roblox_AccountInformation_Api_Models_MetadataResponse = zod_1.z.object({
     isAllowedNotificationsEndpointDisabled: zod_1.z.boolean(),
     isAccountSettingsPolicyEnabled: zod_1.z.boolean(),
@@ -34,9 +28,9 @@ const Roblox_AccountInformation_Api_Models_MetadataResponse = zod_1.z.object({
     MaxUserDescriptionLength: zod_1.z.number().int(),
     isUserDescriptionEnabled: zod_1.z.boolean(),
     isUserBlockEndpointsUpdated: zod_1.z.boolean(),
-    isPasswordRequiredForAgingDown: zod_1.z.boolean(),
     shouldUsePersonaForIdVerification: zod_1.z.boolean(),
     shouldDisplaySessionManagement: zod_1.z.boolean(),
+    isPasswordRequiredForAgingDown: zod_1.z.boolean(),
 });
 const Roblox_AccountInformation_Api_Models_PhoneResponse = zod_1.z.object({
     countryCode: zod_1.z.string(),
@@ -94,7 +88,6 @@ const Roblox_AccountInformation_Api_RobloxBadgeResponse = zod_1.z.object({
     description: zod_1.z.string(),
     imageUrl: zod_1.z.string(),
 });
-const Roblox_AccountInformation_Api_Models_ConsecutiveLoginDaysResponse = zod_1.z.object({ count: zod_1.z.number().int() });
 const Roblox_AccountInformation_Api_Models_VerifyEmailRequest = zod_1.z.object({
     ticket: zod_1.z.string(),
 });
@@ -126,45 +119,6 @@ exports.getBirthdate = (0, __1.endpoint)({
         },
     ],
 });
-/**
- * @api POST https://accountinformation.roblox.com/v1/birthdate
- * @summary Update the user's birthdate
- * @param body The Roblox.AccountInformation.Api.Models.BirthdateRequest
- */
-exports.postBirthdate = (0, __1.endpoint)({
-    method: 'POST',
-    path: '/v1/birthdate',
-    baseUrl: 'https://accountinformation.roblox.com',
-    requestFormat: 'json',
-    serializationMethod: {
-        body: {},
-    },
-    parameters: {},
-    body: Roblox_AccountInformation_Api_Models_BirthdateRequest,
-    response: zod_1.z.object({}),
-    errors: [
-        {
-            status: 400,
-            description: `1: User not found.
-4: The birthdate provided is invalid.
-8: Password is incorrect.`,
-        },
-        {
-            status: 401,
-            description: `0: Authorization has been denied for this request.`,
-        },
-        {
-            status: 403,
-            description: `0: Token Validation Failed
-5: Invalid birthdate change.`,
-        },
-        {
-            status: 500,
-            description: `0: An unknown error occured.
-5: Invalid birthdate change.`,
-        },
-    ],
-});
 /**
  * @api GET https://accountinformation.roblox.com/v1/description
  * @summary Get the user's description
@@ -729,21 +683,3 @@ exports.getUsersUseridRobloxBadges = (0, __1.endpoint)({
     response: zod_1.z.array(Roblox_AccountInformation_Api_RobloxBadgeResponse),
     errors: [],
 });
-/**
- * @api GET https://accountinformation.roblox.com/v1/xbox-live/consecutive-login-days
- * @summary Returns number of consecutive login days for xbox users
- */
-exports.getXboxLiveConsecutiveLoginDays = (0, __1.endpoint)({
-    method: 'GET',
-    path: '/v1/xbox-live/consecutive-login-days',
-    baseUrl: 'https://accountinformation.roblox.com',
-    requestFormat: 'json',
-    response: zod_1.z.object({ count: zod_1.z.number().int() }),
-    errors: [
-        {
-            status: 401,
-            description: `0: Authorization has been denied for this request.
-7: The account is not connected to an Xbox Live account`,
-        },
-    ],
-});

package/lib/endpoints/adconfigurationv2.d.ts

@@ -344,7 +344,7 @@ export const getSponsoredCampaignsMultiGetCanUserSponsor = endpoint({
     campaignTargetType: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]),
     campaignTargetIds: z.array(z.number()),
   },
-  response: z.record(z.string(), z.boolean()),
+  response: z.boolean(),
   errors: [
     {
       status: 400,