@arkyn/server 3.0.1-beta.9 → 3.0.1-beta.91

package/README.md

@@ -1,116 +1,419 @@
-The `@arkyn/server` package provides utilities and services to streamline backend application development. It includes API configurations, HTTP error handlers, and various services for file manipulation.
+# @arkyn/server
 
----
+A comprehensive server-side utilities package for building robust backend applications. Provides HTTP response helpers, error handlers, request utilities, and pre-configured API instances to streamline your server-side development workflow.
+
+[![npm version](https://img.shields.io/npm/v/@arkyn/server.svg)](https://www.npmjs.com/package/@arkyn/server)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-## Installation
+## ✨ Features
 
-Install the package using npm:
+- 🌐 **HTTP Response Helpers** - Pre-built success and error response functions
+- ⚙️ **API Configurations** - Ready-to-use API and logging instances
+- 🔍 **Request Utilities** - Body parsing, parameter extraction, and debugging tools
+- 🛡️ **Error Handling** - Comprehensive error handling and validation
+- 🧪 **Schema Validation** - Zod integration for data validation
+- 🚀 **Remix Integration** - Optimized for React Router and Remix applications
+
+## 📦 Installation
 
 ```bash
 npm install @arkyn/server
 ```
 
----
+## 🚀 Quick Start
 
-## Features
+```typescript
+import { Success, BadRequest, errorHandler } from "@arkyn/server";
 
-### Settings
+export async function loader({ request }: LoaderFunctionArgs) {
+  try {
+    const data = await fetchUserData();
+    return Success(data);
+  } catch (error) {
+    return errorHandler(error);
+  }
+}
 
-- **`ApiInstance`**  
-  Pre-configured instance for API calls.
+export async function action({ request }: ActionFunctionArgs) {
+  const body = await decodeRequestBody(request);
 
-- **`ArkynLogInstance`**  
-  Pre-configured instance for integration with Inbox Flow.
+  if (!body.email) {
+    return BadRequest("Email is required");
+  }
 
----
+  const user = await createUser(body);
+  return Created(user);
+}
+```
 
-### HTTP Responses - Errors
+## 📋 API Reference
 
-- **`BadGateway(message: string): Error`**  
-  Represents an HTTP 502 error.
+### Configuration
 
-- **`BadRequest(message: string): Error`**  
-  Represents an HTTP 400 error.
+#### ApiInstance
 
-- **`Conflict(message: string): Error`**  
-  Represents an HTTP 409 error.
+Pre-configured Axios instance for external API calls.
 
-- **`Forbidden(message: string): Error`**  
-  Represents an HTTP 403 error.
+```typescript
+import { ApiInstance } from "@arkyn/server";
 
-- **`NotFound(message: string): Error`**  
-  Represents an HTTP 404 error.
+const api = new ApiInstance({ baseUrl: "https://google.com" });
+const response = await api.get("/users");
+```
 
-- **`NotImplemented(message: string): Error`**  
-  Represents an HTTP 501 error.
+#### ArkynLogInstance
 
-- **`ServerError(message: string): Error`**  
-  Represents an HTTP 500 error.
+Pre-configured instance for integration with logging services.
 
-- **`Unauthorized(message: string): Error`**  
-  Represents an HTTP 401 error.
+```typescript
+import { ArkynLogInstance } from "@arkyn/server";
 
-- **`UnprocessableEntity(message: string): Error`**  
-  Represents an HTTP 422 error.
+ArkynLogInstance.setArkynConfig();
+```
 
 ---
 
-### HTTP Responses - Success
+### HTTP Error Responses
 
-- **`Created(data: any): Response`**  
-  Represents an HTTP 201 response.
+#### BadRequest(message: string): Error
 
-- **`Found(data: any): Response`**  
-  Represents an HTTP 302 response.
+Returns HTTP 400 for client errors.
 
-- **`NoContent(): Response`**  
-  Represents an HTTP 204 response.
+```typescript
+import { BadRequest } from "@arkyn/server";
+
+if (!email) {
+  return BadRequest("Email is required");
+}
+```
+
+#### Unauthorized(message: string): Error
+
+Returns HTTP 401 for authentication errors.
+
+```typescript
+import { Unauthorized } from "@arkyn/server";
+
+if (!isAuthenticated) {
+  return Unauthorized("Authentication required");
+}
+```
 
-- **`Success(data: any): Response`**  
-  Represents an HTTP 200 response.
+#### Forbidden(message: string): Error
+
+Returns HTTP 403 for authorization errors.
+
+```typescript
+import { Forbidden } from "@arkyn/server";
+
+if (!hasPermission) {
+  return Forbidden("Insufficient permissions");
+}
+```
+
+#### NotFound(message: string): Error
+
+Returns HTTP 404 for missing resources.
+
+```typescript
+import { NotFound } from "@arkyn/server";
+
+const user = await findUser(id);
+if (!user) {
+  return NotFound("User not found");
+}
+```
+
+#### Conflict(message: string): Error
+
+Returns HTTP 409 for resource conflicts.
+
+```typescript
+import { Conflict } from "@arkyn/server";
+
+const existingUser = await findUserByEmail(email);
+if (existingUser) {
+  return Conflict("Email already exists");
+}
+```
 
-- **`Updated(data: any): Response`**  
-  Represents an HTTP 200 response for updates.
+#### UnprocessableEntity(message: string): Error
+
+Returns HTTP 422 for validation errors.
+
+```typescript
+import { UnprocessableEntity } from "@arkyn/server";
+
+if (!isValidEmail(email)) {
+  return UnprocessableEntity("Invalid email format");
+}
+```
+
+#### ServerError(message: string): Error
+
+Returns HTTP 500 for internal errors.
+
+#### BadGateway(message: string): Error
+
+Returns HTTP 502 for gateway errors.
+
+#### NotImplemented(message: string): Error
+
+Returns HTTP 501 for unimplemented features.
 
 ---
 
-### Services
+### HTTP Success Responses
+
+#### Success(data: any): Response
+
+Returns HTTP 200 with data.
+
+```typescript
+import { Success } from "@arkyn/server";
+
+export async function loader() {
+  const users = await getUsers();
+  return Success(users);
+}
+```
+
+#### Created(data: any): Response
+
+Returns HTTP 201 for successful creation.
+
+```typescript
+import { Created } from "@arkyn/server";
+
+export async function action({ request }) {
+  const user = await createUser(await request.json());
+  return Created(user);
+}
+```
+
+#### Updated(data: any): Response
 
-- **`decodeErrorMessageFromRequest(request: Request): string`**  
-  Decodes error messages from a request.
+Returns HTTP 200 for successful updates.
 
-- **`decodeRequestBody(request: Request): any`**  
-  Decodes the body of a request.
+```typescript
+import { Updated } from "@arkyn/server";
 
-- **`errorHandler(error: Error): Response`**  
-  Handles errors and returns an appropriate response.
+const updatedUser = await updateUser(id, data);
+return Updated(updatedUser);
+```
+
+#### NoContent(): Response
 
-- **`formParse(request: Request): FormData`**  
-  Parses form data.
+Returns HTTP 204 for successful operations without content.
 
-- **`getCaller(): string`**  
-  Returns the name of the function that invoked the method.
+```typescript
+import { NoContent } from "@arkyn/server";
 
-- **`getScopedParams(request: Request): URLSearchParams`**  
-  Retrieves scoped parameters from a request.
+await deleteUser(id);
+return NoContent();
+```
 
-- **`httpDebug(request: Request): void`**  
-  Displays debug information for an HTTP request.
+#### Found(data: any): Response
 
-- **`SchemaValidator(schema: any, data: any): boolean`**  
-  Validates data against a schema.
+Returns HTTP 302 for redirects with data.
 
-- **`sendFileToS3(file: File, config: AwsConfig): Promise<{ url: string }>`**  
-  Uploads a file to AWS S3.
+```typescript
+import { Found } from "@arkyn/server";
+
+return Found({ redirectUrl: "/dashboard" });
+```
 
 ---
 
-## Contribution
+### Utilities & Services
+
+#### errorHandler(error: Error): Response
+
+Centralized error handling that returns appropriate HTTP responses.
 
-Contributions are welcome! Feel free to open issues or submit pull requests to improve the project.
+```typescript
+import { errorHandler } from "@arkyn/server";
+
+export async function action({ request }) {
+  try {
+    return await processRequest(request);
+  } catch (error) {
+    return errorHandler(error); // Automatically handles different error types
+  }
+}
+```
+
+#### decodeRequestBody(request: Request): any
+
+Safely decodes JSON request bodies.
+
+```typescript
+import { decodeRequestBody } from "@arkyn/server";
+
+export async function action({ request }) {
+  const body = await decodeRequestBody(request);
+  console.log(body); // Parsed JSON object
+}
+```
+
+#### formParse(request: Request): FormData
+
+Parses multipart form data from requests.
+
+```typescript
+import { formParse } from "@arkyn/server";
+
+export async function action({ request }) {
+  const formData = await formParse(request);
+  const file = formData.get("avatar") as File;
+}
+```
+
+#### getScopedParams(request: Request): URLSearchParams
+
+Extracts URL parameters from requests.
+
+```typescript
+import { getScopedParams } from "@arkyn/server";
+
+export async function loader({ request }) {
+  const params = getScopedParams(request);
+  const page = params.get("page") || "1";
+}
+```
+
+#### SchemaValidator(schema: any, data: any): boolean
+
+Validates data against Zod schemas.
+
+```typescript
+import { SchemaValidator } from "@arkyn/server";
+import { z } from "zod";
+
+const userSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+});
+
+export async function action({ request }) {
+  const body = await decodeRequestBody(request);
+
+  if (!SchemaValidator(userSchema, body)) {
+    return BadRequest("Invalid data format");
+  }
+}
+```
+
+#### httpDebug(request: Request): void
+
+Logs detailed information about HTTP requests for debugging.
+
+```typescript
+import { httpDebug } from "@arkyn/server";
+
+export async function loader({ request }) {
+  httpDebug(request); // Logs method, URL, headers, etc.
+}
+```
+
+#### getCaller(): string
+
+Returns the name of the calling function for debugging purposes.
+
+```typescript
+import { getCaller } from "@arkyn/server";
+
+function myFunction() {
+  console.log(`Called from: ${getCaller()}`);
+}
+```
+
+#### decodeErrorMessageFromRequest(request: Request): string
+
+Extracts error messages from request objects.
+
+```typescript
+import { decodeErrorMessageFromRequest } from "@arkyn/server";
+
+const errorMessage = decodeErrorMessageFromRequest(request);
+```
+
+## 🔧 Advanced Usage
+
+### Custom Error Handling
+
+```typescript
+import { errorHandler, BadRequest, ServerError } from "@arkyn/server";
+
+export async function action({ request }) {
+  try {
+    const body = await decodeRequestBody(request);
+
+    // Custom validation
+    if (!body.email) {
+      throw new BadRequest("Email is required");
+    }
+
+    const result = await processData(body);
+    return Success(result);
+  } catch (error) {
+    if (error instanceof BadRequest) {
+      return error; // Return as-is
+    }
+
+    // Log unexpected errors
+    console.error("Unexpected error:", error);
+    return ServerError("Internal server error");
+  }
+}
+```
+
+### Request Pipeline
+
+```typescript
+import {
+  decodeRequestBody,
+  SchemaValidator,
+  getScopedParams,
+  Success,
+  BadRequest,
+} from "@arkyn/server";
+
+export async function action({ request }) {
+  // 1. Parse request
+  const body = await decodeRequestBody(request);
+  const params = getScopedParams(request);
+
+  // 2. Validate
+  if (!SchemaValidator(mySchema, body)) {
+    return BadRequest("Invalid request data");
+  }
+
+  // 3. Process
+  const result = await processRequest(body, params);
+
+  // 4. Respond
+  return Success(result);
+}
+```
 
 ---
 
-## License
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to help improve the package.
+
+## 📄 License
+
+This project is licensed under the Apache 2.0 License - see the [LICENSE](./LICENSE.txt) file for details.
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/Lucas-Eduardo-Goncalves/arkyn)
+- [NPM Package](https://www.npmjs.com/package/@arkyn/server)
+- [Full Documentation](https://github.com/Lucas-Eduardo-Goncalves/arkyn#readme)
+
+---
 
-This project is licensed under the Apache 2.0 License. See the `LICENSE` file for more details.
+Made with ❤️ by the Arkyn team

package/dist/api/arkynLogRequest.d.ts

@@ -26,7 +26,7 @@ type ConfigProps = {
  * @param config.responseBody - The body of the response received.
  *
  * @remarks
- * - This function retrieves the inbox flow configuration using `InboxFlowInstance.getInboxConfig()`.
+ * - This function retrieves the inbox flow configuration using `InboxFlowService.getInboxConfig()`.
  * - If the configuration is not available, the function will return early without performing any action.
  * - In a development environment (`NODE_ENV === "development"`), the function will also return early.
  * - The request is sent as a POST request to the inbox API URL with the provided configuration details.

package/dist/api/arkynLogRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arkynLogRequest.d.ts","sourceRoot":"","sources":["../../src/api/arkynLogRequest.ts"],"names":[],"mappings":"AAGA,KAAK,WAAW,GAAG;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,iBAAe,eAAe,CAAC,MAAM,EAAE,WAAW,iBAiEjD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"arkynLogRequest.d.ts","sourceRoot":"","sources":["../../src/api/arkynLogRequest.ts"],"names":[],"mappings":"AAGA,KAAK,WAAW,GAAG;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,iBAAe,eAAe,CAAC,MAAM,EAAE,WAAW,iBAyDjD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/api/arkynLogRequest.js

@@ -1,5 +1,5 @@
-import { ArkynLogInstance } from "../config/arkynLogInstance";
-import { httpDebug } from "../services/httpDebug";
+import { ArkynLogService } from "../services/arkynLogService";
+import { flushDebugLogs } from "../services/flushDebugLogs";
 /**
  * Sends a request to the inbox flow API with the provided configuration.
  *
@@ -16,7 +16,7 @@ import { httpDebug } from "../services/httpDebug";
  * @param config.responseBody - The body of the response received.
  *
  * @remarks
- * - This function retrieves the inbox flow configuration using `InboxFlowInstance.getInboxConfig()`.
+ * - This function retrieves the inbox flow configuration using `InboxFlowService.getInboxConfig()`.
  * - If the configuration is not available, the function will return early without performing any action.
  * - In a development environment (`NODE_ENV === "development"`), the function will also return early.
  * - The request is sent as a POST request to the inbox API URL with the provided configuration details.
@@ -41,43 +41,48 @@ import { httpDebug } from "../services/httpDebug";
  * ```
  */
 async function arkynLogRequest(config) {
-    const arkynInstance = ArkynLogInstance.getArkynConfig();
-    if (!arkynInstance)
+    const arkynService = ArkynLogService.getArkynConfig();
+    if (!arkynService)
         return;
-    const { arkynUserToken, arkynApiUrl } = arkynInstance;
+    const { userToken, apiUrl, trafficSourceId } = arkynService;
     const { elapsedTime, method, queryParams, requestBody, requestHeaders, responseBody, responseHeaders, status, token, rawUrl, } = config;
-    // if (process.env.NODE_ENV === "development") return;
+    if (process.env.NODE_ENV === "development")
+        return;
     try {
         const url = new URL(rawUrl);
-        let protocol = "HTTPS";
+        let protocol = "https";
         if (url.protocol === "http:")
-            protocol = "HTTP";
+            protocol = "http";
         const body = JSON.stringify({
             domainUrl: url.protocol + "//" + url.host,
             pathnameUrl: url.pathname,
+            trafficSourceId: trafficSourceId,
             status,
             protocol,
-            method,
+            method: method.toLowerCase(),
             trafficUserId: null,
             elapsedTime,
-            requestHeaders,
-            requestBody,
-            queryParams,
-            responseHeaders,
-            responseBody,
+            requestHeaders: JSON.stringify(requestHeaders),
+            requestBody: JSON.stringify(requestBody),
+            queryParams: JSON.stringify(queryParams),
+            responseHeaders: JSON.stringify(responseHeaders),
+            responseBody: JSON.stringify(responseBody),
         });
-        console.log(arkynApiUrl.replace(":trafficSourceId", arkynInstance.arkynTrafficSourceId));
-        await fetch(arkynApiUrl.replace(":trafficSourceId", arkynInstance.arkynTrafficSourceId), {
+        await fetch(apiUrl, {
             method: "POST",
             body,
             headers: {
                 "Content-Type": "application/json",
-                Authorization: `Bearer ${arkynUserToken}`,
+                Authorization: `Bearer ${userToken}`,
             },
         });
     }
     catch (err) {
-        httpDebug("arkyn log error", "Error sending request", err);
+        flushDebugLogs({
+            debugs: [`Error sending request: ${err}`],
+            name: "ARKYN_LOG_ERROR",
+            scheme: "red",
+        });
     }
 }
 export { arkynLogRequest };

package/dist/api/makeRequest.d.ts

@@ -33,6 +33,6 @@ import type { ApiResponseDTO } from "../types/ApiResponseDTO";
  * }
  * ```
  */
-declare function makeRequest<T = any>(method: "POST" | "PUT" | "DELETE" | "PATCH" | "GET", url: string, headers?: HeadersInit, body?: any): Promise<ApiResponseDTO<T>>;
+declare function makeRequest<T = any>(method: "POST" | "PUT" | "DELETE" | "PATCH" | "GET", url: string, rawHeaders?: HeadersInit, body?: any): Promise<ApiResponseDTO<T>>;
 export { makeRequest };
 //# sourceMappingURL=makeRequest.d.ts.map

package/dist/api/makeRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"makeRequest.d.ts","sourceRoot":"","sources":["../../src/api/makeRequest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iBAAe,WAAW,CAAC,CAAC,GAAG,GAAG,EAChC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,EACnD,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,EACzB,IAAI,CAAC,EAAE,GAAG,GACT,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAwE5B;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"makeRequest.d.ts","sourceRoot":"","sources":["../../src/api/makeRequest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iBAAe,WAAW,CAAC,CAAC,GAAG,GAAG,EAChC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,EACnD,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,WAAgB,EAC5B,IAAI,CAAC,EAAE,GAAG,GACT,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA2E5B;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/api/makeRequest.js

@@ -1,5 +1,5 @@
 import { ArkynLogRequestMapper } from "../mapper/arkynLogRequestMapper";
-import { httpDebug } from "../services/httpDebug";
+import { flushDebugLogs } from "../services/flushDebugLogs";
 import { arkynLogRequest } from "./arkynLogRequest";
 /**
  * Makes an HTTP request using the Fetch API and returns a standardized response.
@@ -35,7 +35,7 @@ import { arkynLogRequest } from "./arkynLogRequest";
  * }
  * ```
  */
-async function makeRequest(method, url, headers = {}, body) {
+async function makeRequest(method, url, rawHeaders = {}, body) {
     const successMessage = {
         POST: "Resource created successfully",
         PUT: "Resource updated successfully",
@@ -45,12 +45,10 @@ async function makeRequest(method, url, headers = {}, body) {
     };
     try {
         const startTime = performance.now();
+        const headers = { ...rawHeaders, "Content-Type": "application/json" };
         const response = await fetch(url, {
             method,
-            headers: {
-                ...headers,
-                "Content-Type": "application/json",
-            },
+            headers,
             body: body ? JSON.stringify(body) : undefined,
         });
         const elapsedTime = performance.now() - startTime;
@@ -92,7 +90,11 @@ async function makeRequest(method, url, headers = {}, body) {
         };
     }
     catch (err) {
-        httpDebug("Network error or request failed", null, err);
+        flushDebugLogs({
+            debugs: [`Network error or request failed: ${err}`],
+            name: "ARKYN_MAKE_REQUEST_ERROR",
+            scheme: "red",
+        });
         return {
             success: false,
             status: 0,