api-res-formatter/README.md

A standardized API response formatter built to ensure consistency and clarity in application responses. This formatter wraps success and error responses in a predictable structure, making it easier for clients and developers to handle API interactions eff

## API Response Formatter for GitHub

A standardized API response formatter built to ensure consistency and clarity in GitHub-integrated application responses. This formatter wraps success and error responses in a predictable structure, making it easier for clients and developers to handle API interactions effectively.

---

### Table of Contents

- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Response Structure](#response-structure)
  - [Success Format](#success-format)
  - [Error Format](#error-format)
- [Examples](#examples)
- [Features](#features)
- [Configuration](#configuration)
- [Dependencies](#dependencies)
- [Troubleshooting](#troubleshooting)
- [Contributors](#contributors)
- [License](#license)
- [Conclusion](#conclusion)

---

### Introduction

When building APIs that interact with GitHub or its ecosystem, maintaining a clean and uniform response format is crucial for debugging, monitoring, and client development. The **API Response Formatter** is a plug-and-play middleware or utility function that ensures every outgoing response follows a predictable schema, including HTTP status codes, messages, data payloads, and error descriptions.

This utility is ideal for RESTful APIs, GitHub webhook handlers, or GitHub Actions that return JSON responses.

---

### Installation

Install via npm:

```bash
npm install api-response-formatter
```

Or with yarn:

```bash
yarn add api-response-formatter
```

---

### Usage

Import and use in your application:

### JavaScript / Node.js (Express example)

```javascript
const express = require('express');
const { formatSuccess, formatError } = require('github-api-response-formatter');

const app = express();

app.get('/status', (req, res) => {
  const data = { status: 'OK', timestamp: new Date() };
  return res.status(200).json(formatSuccess(data, 'Status fetched successfully.'));
});

app.get('/error', (req, res) => {
  const errorDetails = { code: 'NOT_FOUND', reason: 'Item does not exist' };
  return res.status(404).json(formatError(errorDetails, 'Requested resource not found.'));
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});
```

---

### Response Structure

### Success Format

```json
{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    // your payload here
  },
  "timestamp": "2025-05-03T12:34:56.789Z"
}
```

### Error Format

```json
{
  "success": false,
  "message": "Resource not found.",
  "error": {
    "code": "NOT_FOUND",
    "details": "The specified repository does not exist or access is denied."
  },
  "timestamp": "2025-05-03T12:34:56.789Z"
}
```

---

### Examples

### GitHub Webhook Handler

```javascript
app.post('/webhook', (req, res) => {
  try {
    // Process GitHub event
    return res.json(formatSuccess(null, 'GitHub webhook processed.'));
  } catch (err) {
    return res.status(500).json(formatError({ code: 'WEBHOOK_ERROR', details: err.message }, 'Failed to process webhook.'));
  }
});
```

### API Response with Custom Status Code

```javascript
return res.status(201).json(formatSuccess({ id: 123 }, 'New repository metadata created.'));
```

---

### Features

- ✅ Uniform success and error structures
- 🧪 Easy to test and log
- 🔒 Timestamp included for audit trails
- 🔁 Compatible with REST APIs, GitHub Actions, and Webhooks
- ⚙️ Extendable with custom fields

---

### Configuration

No configuration is required by default.

Optional overrides (if supported in the future):

```javascript
formatSuccess(data, message, customFields);
formatError(errorObject, message, customFields);
```

You can inject custom metadata into responses via `customFields`.

---

### Dependencies

- Node.js ≥ 12.x
- (Optional) Express.js for usage examples

No third-party dependencies unless using the formatter within a specific framework.

---

### Troubleshooting

| Issue                        | Solution                                                                 |
|-----------------------------|--------------------------------------------------------------------------|
| Timestamps are incorrect    | Ensure server timezone is set correctly or handle in client-side logic. |
| Error format not as expected| Verify that error object contains both `code` and `details`.             |
| No response returned        | Confirm that `res.status().json()` is called in your controller logic.  |

---

### Contributors

- [Bhadra Mohit](https://github.com/BhadraMohit09) — Creator & Maintainer

Feel free to open issues or submit pull requests!

---

### License

This project is licensed under the [MIT License](LICENSE).

---

### Conclusion

**API Response Formatter** provides a clean, professional, and standardized way to structure your API outputs, improving development efficiency and debugging clarity across all GitHub-integrated services. Lightweight and easy to integrate, it ensures that both humans and machines can reliably interpret your API responses.