@knsdev/node-utils 1.0.1 → 3.0.0

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,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,cAAc,EAAE,IAAI,GAAG,SAAS,CAAC;IAEjC;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,KAAK,SAAK,EAAE,cAAc,CAAC,EAAE,IAAI;CAQnF;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAChD;;;OAGG;gBACS,OAAO,GAAE,UAAoC,EAAE,KAAK,SAAK;CAKrE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC5C;;;OAGG;gBACS,OAAO,GAAE,UAAgC,EAAE,cAAc,CAAC,EAAE,IAAI;CAG5E;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACvC;;;OAGG;gBACS,OAAO,GAAE,UAA0B,EAAE,KAAK,SAAK;CAK3D;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,QAAQ;IACtC;;;OAGG;gBACS,OAAO,GAAE,UAAwB,EAAE,KAAK,SAAK;CAKzD;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IACzC;;;OAGG;gBACS,OAAO,GAAE,UAA2B,EAAE,KAAK,SAAK;CAK5D;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,QAAQ;IACrC;;;OAGG;gBACS,OAAO,GAAE,UAAwB,EAAE,KAAK,SAAK;CAKzD"}

package/dist/ErrorClasses.js

@@ -0,0 +1,118 @@
+/**
+ * Base error type for API responses.
+ * Extends {@link Error} with an HTTP status code and an API error code.
+ */
+export class ApiError extends Error {
+    status;
+    message;
+    retryAfterDate;
+    /**
+     * @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, message, stack = "", retryAfterDate) {
+        super(message || 'API_ERROR');
+        this.status = status;
+        this.message = message || 'API_ERROR';
+        this.retryAfterDate = retryAfterDate;
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 500 Internal Server Error.
+ */
+export 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 = 'INTERNAL_SERVER_ERROR', stack = "") {
+        super(500, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 429 Too Many Requests.
+ */
+export class TooManyRequests extends ApiError {
+    /**
+     * @param message - API error code (defaults to `TOO_MANY_REQUESTS`).
+     * @param retryAfterDate - Optional date when clients may retry.
+     */
+    constructor(message = 'TOO_MANY_REQUESTS', retryAfterDate) {
+        super(429, message, undefined, retryAfterDate);
+    }
+}
+/**
+ * 400 Bad Request.
+ */
+export 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 = 'BAD_REQUEST', stack = "") {
+        super(400, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 403 Forbidden.
+ */
+export 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 = 'FORBIDDEN', stack = "") {
+        super(403, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 401 Unauthorized.
+ */
+export 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 = 'UNAUTHORIZED', stack = "") {
+        super(401, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 404 Not Found.
+ */
+export 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 = 'NOT_FOUND', stack = "") {
+        super(404, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+//# sourceMappingURL=ErrorClasses.js.map

package/dist/ErrorClasses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorClasses.js","sourceRoot":"","sources":["../src/ErrorClasses.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAClC,MAAM,CAAS;IACf,OAAO,CAAa;IACpB,cAAc,CAAmB;IAEjC;;;;;OAKG;IACH,YAAY,MAAc,EAAE,OAAoB,EAAE,KAAK,GAAG,EAAE,EAAE,cAAqB;QAClF,KAAK,CAAC,OAAO,IAAI,WAAW,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,WAAW,CAAC;QACtC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IAChD;;;OAGG;IACH,YAAY,UAAsB,uBAAuB,EAAE,KAAK,GAAG,EAAE;QACpE,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC5C;;;OAGG;IACH,YAAY,UAAsB,mBAAmB,EAAE,cAAqB;QAC3E,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IAChD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,QAAQ;IACvC;;;OAGG;IACH,YAAY,UAAsB,aAAa,EAAE,KAAK,GAAG,EAAE;QAC1D,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACtC;;;OAGG;IACH,YAAY,UAAsB,WAAW,EAAE,KAAK,GAAG,EAAE;QACxD,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACzC;;;OAGG;IACH,YAAY,UAAsB,cAAc,EAAE,KAAK,GAAG,EAAE;QAC3D,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACrC;;;OAGG;IACH,YAAY,UAAsB,WAAW,EAAE,KAAK,GAAG,EAAE;QACxD,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD"}

package/dist/FBUtils.d.ts

@@ -0,0 +1,22 @@
+declare class facebookUtils {
+    /**
+     * Validates a Facebook access token and fetches user profile details.
+     * Uses POST bodies so tokens and app secrets are not placed in request URLs (fewer access-log leaks).
+     * @param token - Facebook user access token.
+     * @param appId - Facebook application ID.
+     * @param appSecret - Facebook application secret.
+     * @returns Normalized user profile or `null` if token/profile lookup fails.
+     */
+    readonly getUserFromJwt: (token: string, appId: string, appSecret: string) => Promise<{
+        name: string | undefined;
+        email: string | undefined;
+        picture: string | undefined;
+        oauth_id: string;
+    } | null>;
+}
+/**
+ * Singleton instance of Facebook OAuth utilities.
+ */
+export declare const FacebookUtils: facebookUtils;
+export {};
+//# sourceMappingURL=FBUtils.d.ts.map

package/dist/FBUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FBUtils.d.ts","sourceRoot":"","sources":["../src/FBUtils.ts"],"names":[],"mappings":"AAWA,cAAM,aAAa;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,GAAU,OAAO,MAAM,EAAE,OAAO,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC;QAC1F,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC,CA4DR;CACD;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/FBUtils.js

@@ -0,0 +1,68 @@
+import { tryCatch } from "./tryCatch.js";
+const FORM_URLENCODED = "application/x-www-form-urlencoded";
+class facebookUtils {
+    /**
+     * Validates a Facebook access token and fetches user profile details.
+     * Uses POST bodies so tokens and app secrets are not placed in request URLs (fewer access-log leaks).
+     * @param token - Facebook user access token.
+     * @param appId - Facebook application ID.
+     * @param appSecret - Facebook application secret.
+     * @returns Normalized user profile or `null` if token/profile lookup fails.
+     */
+    getUserFromJwt = async (token, appId, appSecret) => {
+        const debugBody = new URLSearchParams({
+            input_token: token,
+            access_token: `${appId}|${appSecret}`,
+        });
+        const [response, error] = await tryCatch(fetch("https://graph.facebook.com/v19.0/debug_token", {
+            method: "POST",
+            headers: { "Content-Type": FORM_URLENCODED },
+            body: debugBody.toString(),
+        }));
+        if (error) {
+            return null;
+        }
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        if (!data.data?.is_valid || data.data.app_id !== appId) {
+            return null;
+        }
+        // `expires_at === 0` is treated as non-expiring (avoid rejecting valid long-lived tokens).
+        const nowSec = Date.now() / 1000;
+        if (data.data.expires_at !== 0 && data.data.expires_at < nowSec) {
+            return null;
+        }
+        const meBody = new URLSearchParams({
+            fields: "id,name,email,picture.type(large)",
+            access_token: token,
+        });
+        const [user, userError] = await tryCatch(fetch("https://graph.facebook.com/v19.0/me", {
+            method: "POST",
+            headers: { "Content-Type": FORM_URLENCODED },
+            body: meBody.toString(),
+        }));
+        if (userError) {
+            return null;
+        }
+        if (!user.ok) {
+            return null;
+        }
+        const userData = (await user.json());
+        if (!userData.id) {
+            return null;
+        }
+        return {
+            oauth_id: userData.id,
+            name: userData.name ?? 'Anonymous',
+            email: userData.email,
+            picture: userData.picture?.data?.url ?? ``,
+        };
+    };
+}
+/**
+ * Singleton instance of Facebook OAuth utilities.
+ */
+export const FacebookUtils = new facebookUtils();
+//# sourceMappingURL=FBUtils.js.map

package/dist/FBUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FBUtils.js","sourceRoot":"","sources":["../src/FBUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AASzC,MAAM,eAAe,GAAG,mCAAmC,CAAC;AAE5D,MAAM,aAAa;IAClB;;;;;;;OAOG;IACM,cAAc,GAAG,KAAK,EAAE,KAAa,EAAE,KAAa,EAAE,SAAiB,EAKtE,EAAE;QAEX,MAAM,SAAS,GAAG,IAAI,eAAe,CAAC;YACrC,WAAW,EAAE,KAAK;YAClB,YAAY,EAAE,GAAG,KAAK,IAAI,SAAS,EAAE;SACrC,CAAC,CAAC;QAEH,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,8CAA8C,EAAE;YAC9F,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE;YAC5C,IAAI,EAAE,SAAS,CAAC,QAAQ,EAAE;SAC1B,CAAC,CAAC,CAAC;QACJ,IAAI,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyE,CAAC;QAC7G,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YACxD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,2FAA2F;QAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,MAAM,EAAE,CAAC;YACjE,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;YAClC,MAAM,EAAE,mCAAmC;YAC3C,YAAY,EAAE,KAAK;SACnB,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,qCAAqC,EAAE;YACrF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE;YAC5C,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE;SACvB,CAAC,CAAC,CAAC;QACJ,IAAI,SAAS,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAkB,CAAC;QACtD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,OAAO;YACN,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,WAAW;YAClC,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE;SAC1C,CAAC;IACH,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC"}

package/dist/GoogleUtils.d.ts

@@ -0,0 +1,43 @@
+declare class googleUtils {
+    /**
+     * Verifies a Google ID token and returns normalized user info.
+     * @param jwtToken - Google ID token.
+     * @param client_id - OAuth client ID expected in token audience.
+     * @returns Normalized user object, or `null` when verification fails.
+     */
+    readonly getUserFromJwt: (jwtToken: string, client_id: string) => Promise<{
+        name: string;
+        email: string | undefined;
+        picture: string;
+        oauth_id: string;
+    } | null>;
+    /**
+     * Exchanges an authorization code for an ID token, then resolves user info.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns Normalized user object, or `null` on failure.
+     */
+    readonly getUserFromCode: (code: string, client_id: string, client_secret: string, redirect_uri: string) => Promise<{
+        name: string | undefined;
+        email: string | undefined;
+        picture: string | undefined;
+        oauth_id: string;
+    } | null>;
+    /**
+     * Exchange Google OAuth authorization code for an ID token.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns ID token string, or `null` on failure.
+     */
+    private readonly jwtFromCode;
+}
+/**
+ * Singleton instance of Google OAuth utilities.
+ */
+export declare const GoogleUtils: googleUtils;
+export {};
+//# sourceMappingURL=GoogleUtils.d.ts.map

package/dist/GoogleUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleUtils.d.ts","sourceRoot":"","sources":["../src/GoogleUtils.ts"],"names":[],"mappings":"AA6BA,cAAM,WAAW;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,GAAU,UAAU,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC;QAC9E,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC,CAeR;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,GAAU,MAAM,MAAM,EAAE,WAAW,MAAM,EAAE,eAAe,MAAM,EAAE,cAAc,MAAM,KAAG,OAAO,CAAC;QACxH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC,CAIR;IAGD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAqB3B;CACD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC"}

package/dist/GoogleUtils.js

@@ -0,0 +1,79 @@
+import { createRemoteJWKSet } from "jose/jwks/remote";
+import { tryCatch } from "./tryCatch.js";
+import { jwtVerify } from "jose";
+const Google_JWK = createRemoteJWKSet(new URL("https://www.googleapis.com/oauth2/v3/certs"));
+class googleUtils {
+    /**
+     * Verifies a Google ID token and returns normalized user info.
+     * @param jwtToken - Google ID token.
+     * @param client_id - OAuth client ID expected in token audience.
+     * @returns Normalized user object, or `null` when verification fails.
+     */
+    getUserFromJwt = async (jwtToken, client_id) => {
+        if (!Google_JWK)
+            return null;
+        const [data, error] = await tryCatch(jwtVerify(jwtToken, Google_JWK, {
+            issuer: "https://accounts.google.com",
+            audience: client_id,
+        }));
+        if (error)
+            return null;
+        return {
+            name: data.payload.name ?? 'Anonymous',
+            email: data.payload.email,
+            picture: data.payload.picture ?? ``,
+            oauth_id: data.payload.sub,
+        };
+    };
+    /**
+     * Exchanges an authorization code for an ID token, then resolves user info.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns Normalized user object, or `null` on failure.
+     */
+    getUserFromCode = async (code, client_id, client_secret, redirect_uri) => {
+        const id_token = await this.jwtFromCode(code, client_id, client_secret, redirect_uri);
+        if (!id_token)
+            return null;
+        return await this.getUserFromJwt(id_token, client_id);
+    };
+    /**
+     * Exchange Google OAuth authorization code for an ID token.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns ID token string, or `null` on failure.
+     */
+    jwtFromCode = async (code, client_id, client_secret, redirect_uri) => {
+        const [resData, error] = await tryCatch(fetch(`https://oauth2.googleapis.com/token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            body: JSON.stringify({
+                code,
+                client_id,
+                client_secret,
+                redirect_uri,
+                grant_type: 'authorization_code'
+            })
+        }));
+        if (error)
+            return null;
+        if (!resData.ok)
+            return null;
+        const data = await resData.json();
+        if (!data.id_token)
+            return null;
+        return data.id_token;
+    };
+}
+/**
+ * Singleton instance of Google OAuth utilities.
+ */
+export const GoogleUtils = new googleUtils();
+//# sourceMappingURL=GoogleUtils.js.map

package/dist/GoogleUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleUtils.js","sourceRoot":"","sources":["../src/GoogleUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAuBjC,MAAM,UAAU,GAAG,kBAAkB,CACpC,IAAI,GAAG,CAAC,4CAA4C,CAAC,CACrD,CAAC;AAEF,MAAM,WAAW;IAChB;;;;;OAKG;IACM,cAAc,GAAG,KAAK,EAAE,QAAgB,EAAE,SAAiB,EAK1D,EAAE;QACX,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAE7B,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAoB,QAAQ,EAAE,UAAU,EAAE;YACvF,MAAM,EAAE,6BAA6B;YACrC,QAAQ,EAAE,SAAS;SACnB,CAAC,CAAC,CAAC;QAEJ,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;QACvB,OAAO;YACN,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,WAAW;YACtC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;YACzB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE;YACnC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;SAC1B,CAAC;IACH,CAAC,CAAA;IAED;;;;;;;OAOG;IACM,eAAe,GAAG,KAAK,EAAE,IAAY,EAAE,SAAiB,EAAE,aAAqB,EAAE,YAAoB,EAKpG,EAAE;QACX,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;QACtF,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3B,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC,CAAA;IAGD;;;;;;;OAOG;IACc,WAAW,GAAG,KAAK,EAAE,IAAY,EAAE,SAAiB,EAAE,aAAqB,EAAE,YAAoB,EAA0B,EAAE;QAC7I,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,qCAAqC,EAAE;YACpF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACR,cAAc,EAAE,kBAAkB;gBAClC,QAAQ,EAAE,kBAAkB;aAC5B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACpB,IAAI;gBACJ,SAAS;gBACT,aAAa;gBACb,YAAY;gBACZ,UAAU,EAAE,oBAAoB;aAChC,CAAC;SACF,CAAC,CAAC,CAAC;QAEJ,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAgC,CAAC;QAChE,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/HMACUtils.d.ts

@@ -0,0 +1,40 @@
+/**
+ * HMAC utilities for use across projects.
+ * Import via: @sajjat/utils/HMACUtils
+ */
+declare class hMACUtils {
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     */
+    readonly hash: (secret: string, token: string) => {
+        data: string;
+        error: null;
+    } | {
+        data: null;
+        error: Error;
+    };
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     *
+     * @throws {Error} If the hashing fails.
+     */
+    readonly hashOrThrow: (secret: string, token: string) => string;
+    /**
+     * Timing-safe comparison of two strings or buffers.
+     * Prevents timing attacks by comparing the full length of the values.
+     * @param a - First value.
+     * @param b - Second value.
+     * @returns True if values match, false otherwise.
+     */
+    readonly compare: (a: string | Buffer, b: string | Buffer) => boolean;
+}
+export declare const HMACUtils: hMACUtils;
+export declare const aaa = 1;
+export {};
+//# sourceMappingURL=HMACUtils.d.ts.map

package/dist/HMACUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HMACUtils.d.ts","sourceRoot":"","sources":["../src/HMACUtils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,cAAM,SAAS;IAEd;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAa5G;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG,MAAM,CAE7D;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,GAAI,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,MAAM,KAAG,OAAO,CAcnE;CACD;AAED,eAAO,MAAM,SAAS,WAAkB,CAAC;AAEzC,eAAO,MAAM,GAAG,IAAI,CAAC"}

package/dist/HMACUtils.js

@@ -0,0 +1,62 @@
+import { createHmac, timingSafeEqual } from "crypto";
+/**
+ * HMAC utilities for use across projects.
+ * Import via: @sajjat/utils/HMACUtils
+ */
+class hMACUtils {
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     */
+    hash = (secret, token) => {
+        try {
+            return {
+                data: this.hashOrThrow(secret, token),
+                error: null
+            };
+        }
+        catch (error) {
+            return {
+                data: null,
+                error: error
+            };
+        }
+    };
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     *
+     * @throws {Error} If the hashing fails.
+     */
+    hashOrThrow = (secret, token) => {
+        return createHmac("sha256", secret).update(token, "utf8").digest("hex");
+    };
+    /**
+     * Timing-safe comparison of two strings or buffers.
+     * Prevents timing attacks by comparing the full length of the values.
+     * @param a - First value.
+     * @param b - Second value.
+     * @returns True if values match, false otherwise.
+     */
+    compare = (a, b) => {
+        try {
+            const aBuf = Buffer.isBuffer(a) ? a : Buffer.from(a, 'utf8');
+            const bBuf = Buffer.isBuffer(b) ? b : Buffer.from(b, 'utf8');
+            // timingSafeEqual throws if lengths do not match
+            if (aBuf.length !== bBuf.length) {
+                return false;
+            }
+            return timingSafeEqual(aBuf, bBuf);
+        }
+        catch {
+            return false;
+        }
+    };
+}
+export const HMACUtils = new hMACUtils();
+export const aaa = 1;
+//# sourceMappingURL=HMACUtils.js.map

package/dist/HMACUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HMACUtils.js","sourceRoot":"","sources":["../src/HMACUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAGrD;;;GAGG;AACH,MAAM,SAAS;IAEd;;;;;OAKG;IACM,IAAI,GAAG,CAAC,MAAc,EAAE,KAAa,EAAgE,EAAE;QAC/G,IAAI,CAAC;YACJ,OAAO;gBACN,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC;gBACrC,KAAK,EAAE,IAAI;aACX,CAAC;QACH,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACd,OAAO;gBACN,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,KAAc;aACrB,CAAC;QACH,CAAC;IACF,CAAC,CAAA;IAED;;;;;;;OAOG;IACM,WAAW,GAAG,CAAC,MAAc,EAAE,KAAa,EAAU,EAAE;QAChE,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACzE,CAAC,CAAA;IAED;;;;;;OAMG;IACM,OAAO,GAAG,CAAC,CAAkB,EAAE,CAAkB,EAAW,EAAE;QACtE,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC7D,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAE7D,iDAAiD;YACjD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjC,OAAO,KAAK,CAAC;YACd,CAAC;YAED,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC,CAAA;CACD;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;AAEzC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC"}

package/dist/HttpCodes.d.ts

@@ -0,0 +1,26 @@
+export declare const HttpCodes: {
+    readonly UNKNOWN_ERROR: 0;
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly NO_CONTENT: 204;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly BAD_GATEWAY: 502;
+    readonly TIMEOUT: 504;
+    readonly ACCEPTED: 202;
+    readonly PARTIAL_CONTENT: 206;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly SEE_OTHER: 303;
+    readonly NOT_MODIFIED: 304;
+    readonly USE_PROXY: 305;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly TOO_MANY_REQUESTS: 429;
+};
+export type THttpCodes = typeof HttpCodes;
+//# sourceMappingURL=HttpCodes.d.ts.map

package/dist/HttpCodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpCodes.d.ts","sourceRoot":"","sources":["../src/HttpCodes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;CAuBZ,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,OAAO,SAAS,CAAC"}

package/dist/HttpCodes.js

@@ -0,0 +1,25 @@
+export const HttpCodes = {
+    UNKNOWN_ERROR: 0,
+    OK: 200,
+    CREATED: 201,
+    NO_CONTENT: 204,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    INTERNAL_SERVER_ERROR: 500,
+    SERVICE_UNAVAILABLE: 503,
+    BAD_GATEWAY: 502,
+    TIMEOUT: 504,
+    ACCEPTED: 202,
+    PARTIAL_CONTENT: 206,
+    MOVED_PERMANENTLY: 301,
+    FOUND: 302,
+    SEE_OTHER: 303,
+    NOT_MODIFIED: 304,
+    USE_PROXY: 305,
+    TEMPORARY_REDIRECT: 307,
+    PERMANENT_REDIRECT: 308,
+    TOO_MANY_REQUESTS: 429,
+};
+//# sourceMappingURL=HttpCodes.js.map

package/dist/HttpCodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpCodes.js","sourceRoot":"","sources":["../src/HttpCodes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG;IACxB,aAAa,EAAE,CAAC;IAChB,EAAE,EAAE,GAAG;IACP,OAAO,EAAE,GAAG;IACZ,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,GAAG;IAChB,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,qBAAqB,EAAE,GAAG;IAC1B,mBAAmB,EAAE,GAAG;IACxB,WAAW,EAAE,GAAG;IAChB,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,eAAe,EAAE,GAAG;IACpB,iBAAiB,EAAE,GAAG;IACtB,KAAK,EAAE,GAAG;IACV,SAAS,EAAE,GAAG;IACd,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,kBAAkB,EAAE,GAAG;IACvB,kBAAkB,EAAE,GAAG;IACvB,iBAAiB,EAAE,GAAG;CACb,CAAC"}

package/dist/IDUtils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Utilities for generating and validating IDs.
+ */
+declare class idUtils {
+    /**
+     * Generates a crypto-random RFC4122 v4 UUID.
+     * @returns A UUID string (e.g. `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`).
+     */
+    readonly gen: () => string;
+    /**
+     * Validates a UUID.
+     * @param id - The UUID to validate.
+     * @returns True if the UUID is valid, false otherwise.
+     */
+    readonly validateOrThrow: (id: unknown) => id is string;
+    /**
+     * Validates that the provided value is a UUID string.
+     * @param id - Value to validate.
+     * @returns `true` when `id` is a valid UUID string.
+     */
+    readonly validate: (id: unknown) => id is string;
+}
+/**
+ * Singleton instance of ID utilities.
+ */
+export declare const IDUtils: idUtils;
+export {};
+//# sourceMappingURL=IDUtils.d.ts.map

package/dist/IDUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IDUtils.d.ts","sourceRoot":"","sources":["../src/IDUtils.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,cAAM,OAAO;IAEZ;;;OAGG;IACH,SAAgB,GAAG,eAElB;IAED;;;;OAIG;IACH,SAAgB,eAAe,GAAI,IAAI,OAAO,KAAG,EAAE,IAAI,MAAM,CAO5D;IAED;;;;OAIG;IACH,SAAgB,QAAQ,GAAI,IAAI,OAAO,KAAG,EAAE,IAAI,MAAM,CAUrD;CACD;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,SAAgB,CAAC"}

package/dist/IDUtils.js

@@ -0,0 +1,47 @@
+import { BadRequest } from "./ErrorClasses.js";
+import { randUuid } from "./Rand.js";
+import { validateUUID } from "./validators.js";
+/**
+ * Utilities for generating and validating IDs.
+ */
+class idUtils {
+    /**
+     * Generates a crypto-random RFC4122 v4 UUID.
+     * @returns A UUID string (e.g. `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`).
+     */
+    gen = () => {
+        return randUuid();
+    };
+    /**
+     * Validates a UUID.
+     * @param id - The UUID to validate.
+     * @returns True if the UUID is valid, false otherwise.
+     */
+    validateOrThrow = (id) => {
+        if (this.validate(id)) {
+            return true;
+        }
+        else {
+            throw new BadRequest('ID__INVALID');
+        }
+    };
+    /**
+     * Validates that the provided value is a UUID string.
+     * @param id - Value to validate.
+     * @returns `true` when `id` is a valid UUID string.
+     */
+    validate = (id) => {
+        if (typeof id === 'string' &&
+            validateUUID(id)) {
+            return true;
+        }
+        else {
+            return false;
+        }
+    };
+}
+/**
+ * Singleton instance of ID utilities.
+ */
+export const IDUtils = new idUtils();
+//# sourceMappingURL=IDUtils.js.map

package/dist/IDUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IDUtils.js","sourceRoot":"","sources":["../src/IDUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;GAEG;AACH,MAAM,OAAO;IAEZ;;;OAGG;IACa,GAAG,GAAG,GAAG,EAAE;QAC1B,OAAO,QAAQ,EAAE,CAAC;IACnB,CAAC,CAAA;IAED;;;;OAIG;IACa,eAAe,GAAG,CAAC,EAAW,EAAgB,EAAE;QAC/D,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;aACI,CAAC;YACL,MAAM,IAAI,UAAU,CAAC,aAAa,CAAC,CAAC;QACrC,CAAC;IACF,CAAC,CAAA;IAED;;;;OAIG;IACa,QAAQ,GAAG,CAAC,EAAW,EAAgB,EAAE;QACxD,IACC,OAAO,EAAE,KAAK,QAAQ;YACtB,YAAY,CAAC,EAAE,CAAC,EACf,CAAC;YACF,OAAO,IAAI,CAAC;QACb,CAAC;aACI,CAAC;YACL,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC"}