@knsdev/node-utils 1.0.1 → 2.0.0

package/README.md

@@ -0,0 +1,363 @@
+# @knsdev/node-utils
+
+TypeScript utilities for Node.js APIs: JWT (HS256), bcrypt passwords, Express cookies, OAuth (Google / Facebook), Cloudflare Turnstile, HMAC, validation helpers, Zod schemas, and small math/random helpers. Published as **ES modules** (`"type": "module"`).
+
+## Requirements
+
+- **Node.js** with native `fetch` (or a compatible runtime).
+- **Express** is a peer-style dependency for [`CookieUtils`](#cookieutils-express) typings and `res.cookie`; install `express` in your app if you use cookies.
+
+## Installation
+
+```bash
+pnpm add @knsdev/node-utils
+# or
+npm install @knsdev/node-utils
+```
+
+Build from source (for contributors):
+
+```bash
+pnpm install
+pnpm run build
+```
+
+## How to import
+
+The package exposes **per-file subpaths** (no root barrel in `exports`):
+
+```ts
+import { JwtUtils } from "@knsdev/node-utils/JwtUtils.js";
+import { tryCatch } from "@knsdev/node-utils/tryCatch.js";
+```
+
+Use the `.js` extension in import specifiers (NodeNext / TypeScript convention for ESM). Paths map to compiled files under `dist/` (e.g. `JwtUtils.ts` → `JwtUtils.js`).
+
+For local monorepos, you can also re-export from the included [`src/index.ts`](src/index.ts) if your bundler resolves it.
+
+---
+
+## Modules and usage
+
+### `tryCatch` / `tryCatch2`
+
+Async and sync helpers that return a **tuple** `[data, error]` instead of throwing.
+
+```ts
+import { tryCatch, tryCatch2 } from "@knsdev/node-utils/tryCatch.js";
+
+const [user, err] = await tryCatch(fetch("https://api.example.com/user"));
+if (err) {
+  console.error(err);
+} else {
+  console.log(await user.json());
+}
+
+const [parsed, parseErr] = tryCatch2(() => JSON.parse('{"a":1}'));
+```
+
+### `getEnvv`
+
+Read `process.env` with a small schema: `string`, `int`, `float`, `boolean`, or `appEnv` (`dev` | `test` | `prod`). Throws a single `Error` listing missing keys and value problems.
+
+```ts
+import { getEnvv } from "@knsdev/node-utils/getEnvv.js";
+
+const env = getEnvv({
+  PORT: "int",
+  DATABASE_URL: "string",
+  APP_ENV: "appEnv",
+  DEBUG: "boolean",
+});
+
+// env.PORT is number, env.APP_ENV is 'dev' | 'test' | 'prod', etc.
+```
+
+### `JwtUtils`
+
+HS256 sign/verify via `jsonwebtoken`. Throwing variants use your API error types (`InternalServerError`, `Unauthorized`, `BadRequest`).
+
+```ts
+import { JwtUtils } from "@knsdev/node-utils/JwtUtils.js";
+
+type Session = { sub: string; role: string };
+
+const token = JwtUtils.signOrThrow<Session>(
+  process.env.JWT_SECRET!,
+  { sub: "user-1", role: "user" },
+  15 * 60 * 1000, // 15 minutes (ignored if payload already has `exp`)
+);
+
+const payload = JwtUtils.verifyOrThrow<Session>(process.env.JWT_SECRET!, token);
+
+const signResult = JwtUtils.sign<Session>(secret, payload, 3600_000);
+if (signResult.error) {
+  /* handle */
+}
+```
+
+### `PasswordUtils`
+
+Bcrypt hash/compare and simple length checks.
+
+```ts
+import { PasswordUtils } from "@knsdev/node-utils/PassUtils.js";
+
+const hashResult = await PasswordUtils.hashPassword("correct horse battery staple");
+if (hashResult.success) {
+  console.log(hashResult.hashedPassword);
+}
+
+const ok = await PasswordUtils.comparePassword("plain", storedHash);
+
+if (!PasswordUtils.validateStrength(pw, 8, 128)) {
+  /* reject */
+}
+
+if (PasswordUtils.isBcryptHash(value)) {
+  /* already a hash */
+}
+```
+
+### `CookieUtils` (Express)
+
+HTTP-only cookies with secure defaults: `secure` follows environment (`dev` allows insecure unless `sameSite === 'none'`).
+
+```ts
+import type { Response } from "express";
+import { CookieUtils } from "@knsdev/node-utils/Cookies.js";
+
+function setSessionCookie(res: Response, token: string) {
+  CookieUtils.setCookie(
+    res,
+    "session",
+    token,
+    7 * 24 * 60 * 60 * 1000,
+    ".example.com",
+    "prod",
+    "/",
+    "lax",
+  );
+}
+
+function logout(res: Response) {
+  CookieUtils.clearCookie(res, "session", ".example.com", "prod");
+}
+```
+
+### `HMACUtils`
+
+SHA-256 HMAC (hex) and timing-safe comparison.
+
+```ts
+import { HMACUtils } from "@knsdev/node-utils/HMACUtils.js";
+
+const { data: digest, error } = HMACUtils.hash(process.env.WEBHOOK_SECRET!, rawBody);
+const valid =
+  digest !== null && HMACUtils.compare(digest, signatureFromHeader);
+```
+
+### `IDUtils` / `validateUUID`
+
+Crypto random UUID (v4) and validation; `validateOrThrow` raises `BadRequest` with `'ID__INVALID'`.
+
+```ts
+import { IDUtils } from "@knsdev/node-utils/IDUtils.js";
+import { validateUUID } from "@knsdev/node-utils/validators.js";
+
+const id = IDUtils.gen();
+
+if (IDUtils.validate(req.params.id)) {
+  /* narrowed to string */
+}
+
+IDUtils.validateOrThrow(req.params.id); // throws BadRequest if invalid
+
+if (validateUUID(someInput)) {
+  /* someInput is string */
+}
+```
+
+### `Rand`
+
+Random integers/floats (crypto vs `Math.random`), UUIDs, and Base58 strings.
+
+```ts
+import { randInt, randUuid, randStr, srandInt } from "@knsdev/node-utils/Rand.js";
+
+const code = randInt(100000, 999999);
+const apiKey = randStr(32);
+const id = randUuid();
+const quickDemo = srandInt(1, 6); // non-crypto, for low-stakes UI
+```
+
+### `Nums`
+
+Clamping, safe parsing, formatting, percentages.
+
+```ts
+import {
+  clamp,
+  parseIntSafe,
+  formatWithCommas,
+  percentage,
+  toNumber,
+} from "@knsdev/node-utils/Nums.js";
+
+const n = clamp(Number(input), 0, 100);
+const page = parseIntSafe(query.page, 10) ?? 1;
+const label = formatWithCommas(12345.67, "en-US", 2);
+const pct = percentage(3, 10, 1); // 30.0
+const x = toNumber(unknownValue, 0);
+```
+
+### `HttpCodes` / `ErrorClasses` / `EApiCodes`
+
+HTTP status constants and errors for APIs: `ApiError` plus `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `TooManyRequests`, `InternalServerError`. Messages use the `EApiCodes` string union (machine-friendly codes for clients).
+
+```ts
+import { HttpCodes } from "@knsdev/node-utils/HttpCodes.js";
+import {
+  BadRequest,
+  Unauthorized,
+  NotFound,
+} from "@knsdev/node-utils/ErrorClasses.js";
+import type { EApiCodes } from "@knsdev/node-utils/EApiCodes.js";
+
+function handler() {
+  throw new BadRequest("EMAIL__INVALID");
+}
+
+function requireUser(token: string | undefined) {
+  if (!token) throw new Unauthorized("UNAUTHORIZED");
+}
+
+// Example Express error middleware pattern:
+// if (err instanceof ApiError) res.status(err.status).json({ code: err.message });
+```
+
+### `GoogleUtils`
+
+Verify Google **ID tokens** with `jose`, or exchange an **authorization code** for tokens and then resolve the user.
+
+```ts
+import { GoogleUtils } from "@knsdev/node-utils/GoogleUtils.js";
+
+const fromIdToken = await GoogleUtils.getUserFromJwt(idToken, process.env.GOOGLE_CLIENT_ID!);
+
+const fromCode = await GoogleUtils.getUserFromCode(
+  code,
+  process.env.GOOGLE_CLIENT_ID!,
+  process.env.GOOGLE_CLIENT_SECRET!,
+  "https://your.app/oauth/callback",
+);
+// Returns { oauth_id, name, email, picture } or null on failure
+```
+
+### `FacebookUtils`
+
+Validates a user access token via Graph API `debug_token`, then loads `/me` (POST bodies to avoid putting secrets in query strings). Returns normalized profile or `null`.
+
+```ts
+import { FacebookUtils } from "@knsdev/node-utils/FBUtils.js";
+
+const profile = await FacebookUtils.getUserFromJwt(
+  accessToken,
+  process.env.FB_APP_ID!,
+  process.env.FB_APP_SECRET!,
+);
+```
+
+### `TurnstileValidator`
+
+Server-side [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) verification. Tuple API or throwing `BadRequest` with `'CAPTCHA__VALIDATION_FAILED'`.
+
+```ts
+import { TurnstileValidator } from "@knsdev/node-utils/TurnstileValidator.js";
+
+const [success, failure] = await TurnstileValidator.validate(
+  process.env.TURNSTILE_SECRET!,
+  tokenFromClient,
+  req.ip,
+  { expectedAction: "login", expectedHostname: "your.app" },
+  10_000,
+  "prod",
+);
+
+if (failure) {
+  console.error(failure["error-codes"]);
+} else {
+  console.log(success.hostname, success.challenge_ts);
+}
+
+// Or throw on any failure:
+const result = await TurnstileValidator.validateOrThrow(
+  secret,
+  tokenFromClient,
+  req.ip,
+  {},
+  10_000,
+  "prod",
+);
+```
+
+### `bnUtils`
+
+Bengali digit substitution and English month → Bengali month names.
+
+```ts
+import { bnNum, monthToBn } from "@knsdev/node-utils/bnUtils.js";
+
+bnNum(2025); // Bengali digits for "2025"
+monthToBn("january");
+monthToBn(3);
+```
+
+### `types`
+
+Shared string unions (app envs, roles, themes, etc.) for use across your app.
+
+```ts
+import type { TAppEnvs, TUserRoles } from "@knsdev/node-utils/types.js";
+
+function configure(env: TAppEnvs) {
+  /* ... */
+}
+```
+
+### `zod` (optional)
+
+Prebuilt Zod schemas aligned with `EApiCodes` / length constants (password, email, slug, 6-digit codes, Turnstile token, etc.).
+
+```ts
+import { z_EMAIL, z_PASSWORD } from "@knsdev/node-utils/zod.js";
+import { z } from "zod";
+
+const LoginBody = z.object({
+  email: z_EMAIL,
+  password: z_PASSWORD,
+});
+```
+
+---
+
+## Dependencies (summary)
+
+| Area            | Packages                          |
+|-----------------|-----------------------------------|
+| JWT             | `jsonwebtoken`                    |
+| Google ID token | `jose`                            |
+| Passwords       | `bcrypt`                          |
+| Schemas         | `zod`                             |
+| Cookies         | `express` (types / `Response`)    |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- [Repository](https://github.com/KnsDev330/node-utils)
+- [Issues](https://github.com/KnsDev330/node-utils/issues)

package/dist/CLengths.d.ts

@@ -0,0 +1,60 @@
+export declare class CLengths {
+    static readonly ID = 36;
+    static readonly UUID = 36;
+    static readonly REFRESH_TOKEN = 64;
+    static readonly ACCOUNT_VERIFY_TOKEN = 64;
+    static readonly GENERAL_TOKEN = 64;
+    static readonly GENERAL_CODE = 6;
+    static readonly Code_8_digits = 8;
+    static readonly Code_6_digits = 6;
+    static readonly Code_4_digits = 4;
+    static readonly SLUG: {
+        min: number;
+        max: number;
+    };
+    static readonly TURNSTILE_TOKEN: {
+        min: number;
+        max: number;
+    };
+    static readonly FIRST_NAME: {
+        min: number;
+        max: number;
+    };
+    static readonly LAST_NAME: {
+        min: number;
+        max: number;
+    };
+    static readonly NAME: {
+        min: number;
+        max: number;
+    };
+    static readonly USERNAME: {
+        min: number;
+        max: number;
+    };
+    static readonly DESIGNATION: {
+        min: number;
+        max: number;
+    };
+    static readonly BIO: {
+        min: number;
+        max: number;
+    };
+    static readonly PASSWORD: {
+        min: number;
+        max: number;
+    };
+    static readonly CONFIRM_PASSWORD: {
+        min: number;
+        max: number;
+    };
+    static readonly EMAIL: {
+        min: number;
+        max: number;
+    };
+    static readonly PHONE: {
+        min: number;
+        max: number;
+    };
+}
+//# sourceMappingURL=CLengths.d.ts.map

package/dist/CLengths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLengths.d.ts","sourceRoot":"","sources":["../src/CLengths.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAQ;IACpB,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM;IACxB,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM;IAC1B,MAAM,CAAC,QAAQ,CAAC,aAAa,MAAM;IACnC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,MAAM;IAC1C,MAAM,CAAC,QAAQ,CAAC,aAAa,MAAM;IACnC,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,aAAa,KAAK;IAClC,MAAM,CAAC,QAAQ,CAAC,aAAa,KAAK;IAClC,MAAM,CAAC,QAAQ,CAAC,aAAa,KAAK;IAElC,MAAM,CAAC,QAAQ,CAAC,IAAI;;;MAGnB;IACD,MAAM,CAAC,QAAQ,CAAC,eAAe;;;MAG9B;IACD,MAAM,CAAC,QAAQ,CAAC,UAAU;;;MAGzB;IACD,MAAM,CAAC,QAAQ,CAAC,SAAS;;;MAGxB;IACD,MAAM,CAAC,QAAQ,CAAC,IAAI;;;MAGnB;IACD,MAAM,CAAC,QAAQ,CAAC,QAAQ;;;MAGvB;IACD,MAAM,CAAC,QAAQ,CAAC,WAAW;;;MAG1B;IACD,MAAM,CAAC,QAAQ,CAAC,GAAG;;;MAGlB;IACD,MAAM,CAAC,QAAQ,CAAC,QAAQ;;;MAGvB;IACD,MAAM,CAAC,QAAQ,CAAC,gBAAgB;;;MAG/B;IACD,MAAM,CAAC,QAAQ,CAAC,KAAK;;;MAGpB;IACD,MAAM,CAAC,QAAQ,CAAC,KAAK;;;MAGpB;CACD"}

package/dist/CLengths.js

@@ -0,0 +1,60 @@
+export class CLengths {
+    static ID = 36;
+    static UUID = 36;
+    static REFRESH_TOKEN = 64;
+    static ACCOUNT_VERIFY_TOKEN = 64;
+    static GENERAL_TOKEN = 64;
+    static GENERAL_CODE = 6;
+    static Code_8_digits = 8;
+    static Code_6_digits = 6;
+    static Code_4_digits = 4;
+    static SLUG = {
+        min: 1,
+        max: 255,
+    };
+    static TURNSTILE_TOKEN = {
+        min: 1,
+        max: 2048,
+    };
+    static FIRST_NAME = {
+        min: 1,
+        max: 50
+    };
+    static LAST_NAME = {
+        min: 0,
+        max: 50
+    };
+    static NAME = {
+        min: 1,
+        max: 100,
+    };
+    static USERNAME = {
+        min: 3,
+        max: 36
+    };
+    static DESIGNATION = {
+        min: 1,
+        max: 255
+    };
+    static BIO = {
+        min: 1,
+        max: 1024
+    };
+    static PASSWORD = {
+        min: 8,
+        max: 128
+    };
+    static CONFIRM_PASSWORD = {
+        min: 8,
+        max: 128
+    };
+    static EMAIL = {
+        min: 5,
+        max: 255
+    };
+    static PHONE = {
+        min: 7,
+        max: 15
+    };
+}
+//# sourceMappingURL=CLengths.js.map

package/dist/CLengths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLengths.js","sourceRoot":"","sources":["../src/CLengths.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAQ;IACpB,MAAM,CAAU,EAAE,GAAG,EAAE,CAAC;IACxB,MAAM,CAAU,IAAI,GAAG,EAAE,CAAC;IAC1B,MAAM,CAAU,aAAa,GAAG,EAAE,CAAC;IACnC,MAAM,CAAU,oBAAoB,GAAG,EAAE,CAAC;IAC1C,MAAM,CAAU,aAAa,GAAG,EAAE,CAAC;IACnC,MAAM,CAAU,YAAY,GAAG,CAAC,CAAC;IACjC,MAAM,CAAU,aAAa,GAAG,CAAC,CAAC;IAClC,MAAM,CAAU,aAAa,GAAG,CAAC,CAAC;IAClC,MAAM,CAAU,aAAa,GAAG,CAAC,CAAC;IAElC,MAAM,CAAU,IAAI,GAAG;QACtB,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,GAAG;KACR,CAAA;IACD,MAAM,CAAU,eAAe,GAAG;QACjC,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,IAAI;KACT,CAAA;IACD,MAAM,CAAU,UAAU,GAAG;QAC5B,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,EAAE;KACP,CAAA;IACD,MAAM,CAAU,SAAS,GAAG;QAC3B,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,EAAE;KACP,CAAA;IACD,MAAM,CAAU,IAAI,GAAG;QACtB,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,GAAG;KACR,CAAA;IACD,MAAM,CAAU,QAAQ,GAAG;QAC1B,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,EAAE;KACP,CAAA;IACD,MAAM,CAAU,WAAW,GAAG;QAC7B,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,GAAG;KACR,CAAA;IACD,MAAM,CAAU,GAAG,GAAG;QACrB,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,IAAI;KACT,CAAA;IACD,MAAM,CAAU,QAAQ,GAAG;QAC1B,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,GAAG;KACR,CAAA;IACD,MAAM,CAAU,gBAAgB,GAAG;QAClC,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,GAAG;KACR,CAAA;IACD,MAAM,CAAU,KAAK,GAAG;QACvB,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,GAAG;KACR,CAAA;IACD,MAAM,CAAU,KAAK,GAAG;QACvB,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,EAAE;KACP,CAAA"}

package/dist/Cookies.d.ts

@@ -0,0 +1,33 @@
+import { type Response } from "express";
+declare class cookieUtils {
+    /**
+     * Set an HTTP-only cookie with common security defaults.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param value - Cookie value.
+     * @param maxAgeMs - Cookie max age in milliseconds (Express `maxAge`).
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    readonly setCookie: (res: Response, name: string, value: string, maxAgeMs: number, domain: string, APP_ENV: "dev" | "test" | "prod", path?: string, sameSite?: "lax" | "strict" | "none") => void;
+    /**
+     * Clear an HTTP-only cookie by setting it expired immediately.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    readonly clearCookie: (res: Response, name: string, domain: string, APP_ENV: "dev" | "test" | "prod", path?: string, sameSite?: "lax" | "strict" | "none") => void;
+}
+/**
+ * Singleton instance of cookie helper utilities.
+ */
+export declare const CookieUtils: cookieUtils;
+export {};
+//# sourceMappingURL=Cookies.d.ts.map

package/dist/Cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cookies.d.ts","sourceRoot":"","sources":["../src/Cookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,cAAM,WAAW;IAChB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,GAAI,KAAK,QAAQ,EAAE,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,UAAU,MAAM,EAAE,QAAQ,MAAM,EAAE,SAAS,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,OAAM,MAAY,EAAE,WAAU,KAAK,GAAG,QAAQ,GAAG,MAAc,UAYpM;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,GAAI,KAAK,QAAQ,EAAE,MAAM,MAAM,EAAE,QAAQ,MAAM,EAAE,SAAS,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,OAAM,MAAY,EAAE,WAAU,KAAK,GAAG,QAAQ,GAAG,MAAc,UAYrK;CACD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC"}

package/dist/Cookies.js

@@ -0,0 +1,54 @@
+import {} from "express";
+class cookieUtils {
+    /**
+     * Set an HTTP-only cookie with common security defaults.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param value - Cookie value.
+     * @param maxAgeMs - Cookie max age in milliseconds (Express `maxAge`).
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    setCookie = (res, name, value, maxAgeMs, domain, APP_ENV, path = '/', sameSite = 'lax') => {
+        // If sameSite is 'none', secure must be true for most modern browsers
+        const isSecure = sameSite === 'none' ? true : APP_ENV !== 'dev';
+        res.cookie(name, value, {
+            httpOnly: true,
+            secure: isSecure,
+            maxAge: maxAgeMs,
+            path: path,
+            sameSite: sameSite,
+            domain: domain
+        });
+    };
+    /**
+     * Clear an HTTP-only cookie by setting it expired immediately.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    clearCookie = (res, name, domain, APP_ENV, path = '/', sameSite = 'lax') => {
+        const isSecure = sameSite === 'none' ? true : APP_ENV !== 'dev';
+        res.cookie(name, 'invalid', {
+            httpOnly: true,
+            secure: isSecure,
+            maxAge: 0,
+            expires: new Date(0),
+            path: path,
+            sameSite: sameSite,
+            domain: domain
+        });
+    };
+}
+/**
+ * Singleton instance of cookie helper utilities.
+ */
+export const CookieUtils = new cookieUtils();
+//# sourceMappingURL=Cookies.js.map

package/dist/Cookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cookies.js","sourceRoot":"","sources":["../src/Cookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW;IAChB;;;;;;;;;;;OAWG;IACM,SAAS,GAAG,CAAC,GAAa,EAAE,IAAY,EAAE,KAAa,EAAE,QAAgB,EAAE,MAAc,EAAE,OAAgC,EAAE,OAAe,GAAG,EAAE,WAAsC,KAAK,EAAE,EAAE;QACxM,sEAAsE;QACtE,MAAM,QAAQ,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;QAEhE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;YACvB,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,MAAM;SACd,CAAC,CAAC;IACJ,CAAC,CAAA;IAED;;;;;;;;;OASG;IACM,WAAW,GAAG,CAAC,GAAa,EAAE,IAAY,EAAE,MAAc,EAAE,OAAgC,EAAE,OAAe,GAAG,EAAE,WAAsC,KAAK,EAAE,EAAE;QACzK,MAAM,QAAQ,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;QAEhE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE;YAC3B,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,CAAC;YACT,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;YACpB,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,MAAM;SACd,CAAC,CAAC;IACJ,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/EApiCodes.d.ts

@@ -0,0 +1,2 @@
+export type EApiCodes = `API_ERROR` | `CREATED` | `UPDATED` | `DELETED` | `FETCHED` | `VALIDATED` | `AUTHENTICATED` | `SUCCESS` | `BAD_REQUEST` | `AUTHORIZED` | `UNAUTHORIZED` | `FORBIDDEN` | `NOT_FOUND` | `INTERNAL_SERVER_ERROR` | `TOO_MANY_REQUESTS` | `JWT__ENCRYPTION_FAILED` | `JWT__INVALID_OR_EXPIRED` | `CAPTCHA__VALIDATION_FAILED` | `PASSWORD__INVALID` | `PASSWORD__MIN_LENGTH` | `PASSWORD__MAX_LENGTH` | `GENERAL_TOKEN__INVALID` | `GENERAL_TOKEN__LENGTH` | `CODE_6_DIGITS__INVALID` | `CODE_6_DIGITS__LENGTH` | `CODE_6_DIGITS__INVALID_FORMAT` | `EMAIL__INVALID` | `EMAIL__MIN_LENGTH` | `EMAIL__MAX_LENGTH` | `FIRST_NAME__INVALID` | `FIRST_NAME__MIN_LENGTH` | `FIRST_NAME__MAX_LENGTH` | `LAST_NAME__INVALID` | `LAST_NAME__MAX_LENGTH` | `TURNSTILE_TOKEN__INVALID` | `TURNSTILE_TOKEN__MIN_LENGTH` | `TURNSTILE_TOKEN__MAX_LENGTH` | `CONFIRM_PASSWORD__DONT_MATCH` | `LOGOUT_OTHER_SESSIONS__INVALID` | `REMEMBER_ME__INVALID` | `SLUG__MIN_LENGTH` | `SLUG__MAX_LENGTH` | `SLUG__NAME__MIN_LENGTH` | `SLUG__NAME__MAX_LENGTH` | `SLUG__DESCRIPTION__MIN_LENGTH` | `SLUG__DESCRIPTION__MAX_LENGTH` | `SLUG__INVALID` | `USERNAME__INVALID` | `USERNAME__MIN_LENGTH` | `USERNAME__MAX_LENGTH` | `DESIGNATION__INVALID` | `DESIGNATION_MAX_LENGTH` | `BIO__INVALID` | `BIO_MAX_LENGTH` | `PROFILE_VISIBILITY__INVALID` | `ID__INVALID`;
+//# sourceMappingURL=EApiCodes.d.ts.map

package/dist/EApiCodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EApiCodes.d.ts","sourceRoot":"","sources":["../src/EApiCodes.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,WAAW,GAClC,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,eAAe,GACf,SAAS,GACT,aAAa,GACb,YAAY,GACZ,cAAc,GACd,WAAW,GACX,WAAW,GACX,uBAAuB,GACvB,mBAAmB,GACnB,wBAAwB,GACxB,yBAAyB,GACzB,4BAA4B,GAC5B,mBAAmB,GACnB,sBAAsB,GACtB,sBAAsB,GACtB,wBAAwB,GACxB,uBAAuB,GACvB,wBAAwB,GACxB,uBAAuB,GACvB,+BAA+B,GAC/B,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,GACnB,qBAAqB,GACrB,wBAAwB,GACxB,wBAAwB,GACxB,oBAAoB,GACpB,uBAAuB,GACvB,0BAA0B,GAC1B,6BAA6B,GAC7B,6BAA6B,GAC7B,8BAA8B,GAC9B,gCAAgC,GAChC,sBAAsB,GACtB,kBAAkB,GAClB,kBAAkB,GAClB,wBAAwB,GACxB,wBAAwB,GACxB,+BAA+B,GAC/B,+BAA+B,GAC/B,eAAe,GACf,mBAAmB,GACnB,sBAAsB,GACtB,sBAAsB,GACtB,sBAAsB,GACtB,wBAAwB,GACxB,cAAc,GACd,gBAAgB,GAChB,6BAA6B,GAC7B,aAAa,CAAC"}

package/dist/EApiCodes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=EApiCodes.js.map

package/dist/EApiCodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EApiCodes.js","sourceRoot":"","sources":["../src/EApiCodes.ts"],"names":[],"mappings":""}

package/dist/ErrorClasses.d.ts

@@ -0,0 +1,78 @@
+import type { EApiCodes } from "./EApiCodes.js";
+/**
+ * Base error type for API responses.
+ * Extends {@link Error} with an HTTP status code and an API error code.
+ */
+export declare class ApiError extends Error {
+    status: number;
+    message: EApiCodes;
+    retryAfterDate: Date | undefined;
+    /**
+     * @param status - HTTP status code associated with the error.
+     * @param message - API error code (defaults to `API_ERROR`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     * @param retryAfterDate - Optional date used for rate-limit responses (e.g. `429`).
+     */
+    constructor(status: number, message?: EApiCodes, stack?: string, retryAfterDate?: Date);
+}
+/**
+ * 500 Internal Server Error.
+ */
+export declare class InternalServerError extends ApiError {
+    /**
+     * @param message - API error code (defaults to `INTERNAL_SERVER_ERROR`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 429 Too Many Requests.
+ */
+export declare class TooManyRequests extends ApiError {
+    /**
+     * @param message - API error code (defaults to `TOO_MANY_REQUESTS`).
+     * @param retryAfterDate - Optional date when clients may retry.
+     */
+    constructor(message?: EApiCodes, retryAfterDate?: Date);
+}
+/**
+ * 400 Bad Request.
+ */
+export declare class BadRequest extends ApiError {
+    /**
+     * @param message - API error code (defaults to `BAD_REQUEST`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 403 Forbidden.
+ */
+export declare class Forbidden extends ApiError {
+    /**
+     * @param message - API error code (defaults to `FORBIDDEN`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 401 Unauthorized.
+ */
+export declare class Unauthorized extends ApiError {
+    /**
+     * @param message - API error code (defaults to `UNAUTHORIZED`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 404 Not Found.
+ */
+export declare class NotFound extends ApiError {
+    /**
+     * @param message - API error code (defaults to `NOT_FOUND`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+//# sourceMappingURL=ErrorClasses.d.ts.map

package/dist/ErrorClasses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorClasses.d.ts","sourceRoot":"","sources":["../src/ErrorClasses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,CAAC;IACnB,cAAc,EAAE,IAAI,GAAG,SAAS,CAAC;IAEjC;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,SAAK,EAAE,cAAc,CAAC,EAAE,IAAI;CAQlF;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAChD;;;OAGG;gBACS,OAAO,GAAE,SAAmC,EAAE,KAAK,SAAK;CAKpE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC5C;;;OAGG;gBACS,OAAO,GAAE,SAA+B,EAAE,cAAc,CAAC,EAAE,IAAI;CAG3E;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACvC;;;OAGG;gBACS,OAAO,GAAE,SAAyB,EAAE,KAAK,SAAK;CAK1D;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,QAAQ;IACtC;;;OAGG;gBACS,OAAO,GAAE,SAAuB,EAAE,KAAK,SAAK;CAKxD;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IACzC;;;OAGG;gBACS,OAAO,GAAE,SAA0B,EAAE,KAAK,SAAK;CAK3D;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,QAAQ;IACrC;;;OAGG;gBACS,OAAO,GAAE,SAAuB,EAAE,KAAK,SAAK;CAKxD"}