rozod 5.0.0 → 6.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2023 Alex Op
+Copyright (c) 2025 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

@@ -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,110 @@ 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, you need to provide the `.ROBLOSECURITY` cookie manually:
+
+```ts
+import { fetchApi } from 'rozod';
+import { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';
+
+const userInfo = await fetchApi(
+  getUsersUserdetails, 
+  { userIds: [123456] },
+  {
+    headers: {
+      'Cookie': '.ROBLOSECURITY=your_cookie_here'
+    }
+  }
+);
+```
+
+### 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 in headers:
+
+```ts
+import { fetchApi } from 'rozod';
+import { v2 } from 'rozod/lib/opencloud';
+
+const universeInfo = await fetchApi(
+  v2.getCloudV2UniversesUniverseId,
+  { universe_id: '123456789' },
+  {
+    headers: {
+      'x-api-key': 'your_opencloud_api_key_here'
     }
+  }
 );
 ```
 
@@ -156,11 +297,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 +309,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/endpoints/accountinformationv1.d.ts

@@ -155,7 +155,6 @@ export const postBirthdate = endpoint({
     {
       status: 403,
       description: `0: Token Validation Failed
-2: PIN is locked.
 5: Invalid birthdate change.`,
     },
     {
@@ -213,8 +212,7 @@ export const postDescription = endpoint({
     },
     {
       status: 403,
-      description: `0: Token Validation Failed
-2: PIN is locked.`,
+      description: `0: Token Validation Failed`,
     },
     {
       status: 500,
@@ -298,8 +296,7 @@ export const postGender = endpoint({
     },
     {
       status: 403,
-      description: `0: Token Validation Failed
-2: PIN is locked.`,
+      description: `0: Token Validation Failed`,
     },
     {
       status: 500,
@@ -370,7 +367,6 @@ export const postPhone = endpoint({
     {
       status: 403,
       description: `0: Token Validation Failed
-4: Account Pin Locked
 5: Incorrect Password
 10: `,
     },
@@ -412,7 +408,6 @@ export const postPhoneDelete = endpoint({
     {
       status: 403,
       description: `0: Token Validation Failed
-4: Account Pin Locked
 5: Incorrect Password`,
     },
     {
@@ -589,7 +584,6 @@ export const postPromotionChannels = endpoint({
     {
       status: 403,
       description: `0: Token Validation Failed
-3: PIN is locked.
 4: Only users who are over twelve years of age may edit social network channels.`,
     },
   ],

package/lib/endpoints/accountinformationv1.js

@@ -156,7 +156,6 @@ exports.postBirthdate = (0, __1.endpoint)({
         {
             status: 403,
             description: `0: Token Validation Failed
-2: PIN is locked.
 5: Invalid birthdate change.`,
         },
         {
@@ -214,8 +213,7 @@ exports.postDescription = (0, __1.endpoint)({
         },
         {
             status: 403,
-            description: `0: Token Validation Failed
-2: PIN is locked.`,
+            description: `0: Token Validation Failed`,
         },
         {
             status: 500,
@@ -299,8 +297,7 @@ exports.postGender = (0, __1.endpoint)({
         },
         {
             status: 403,
-            description: `0: Token Validation Failed
-2: PIN is locked.`,
+            description: `0: Token Validation Failed`,
         },
         {
             status: 500,
@@ -371,7 +368,6 @@ exports.postPhone = (0, __1.endpoint)({
         {
             status: 403,
             description: `0: Token Validation Failed
-4: Account Pin Locked
 5: Incorrect Password
 10: `,
         },
@@ -413,7 +409,6 @@ exports.postPhoneDelete = (0, __1.endpoint)({
         {
             status: 403,
             description: `0: Token Validation Failed
-4: Account Pin Locked
 5: Incorrect Password`,
         },
         {
@@ -590,7 +585,6 @@ exports.postPromotionChannels = (0, __1.endpoint)({
         {
             status: 403,
             description: `0: Token Validation Failed
-3: PIN is locked.
 4: Only users who are over twelve years of age may edit social network channels.`,
         },
     ],