{"id":25219288,"url":"https://github.com/exonos/writer-api","last_synced_at":"2026-02-09T01:31:22.548Z","repository":{"id":276222289,"uuid":"917573143","full_name":"exonos/writer-api","owner":"exonos","description":"A lightweight and scalable microservice for massive document generation using templates and YAML logic, designed for automation, flexibility, and scalability.","archived":false,"fork":false,"pushed_at":"2025-01-21T03:59:37.000Z","size":87,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-07T00:44:36.492Z","etag":null,"topics":["api","automation","contract-automation","docker","document-builder","document-generation","document-maker","docx-templates","fastapi","jinja2","lightweight-microservice","microservice","pdf-generation","python","rest-api","scalable-api","template-engine","yaml-validation"],"latest_commit_sha":null,"homepage":"https://abdielhernandez.com/writer-api","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exonos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-16T08:45:24.000Z","updated_at":"2025-02-04T01:34:32.000Z","dependencies_parsed_at":"2025-02-07T00:44:38.293Z","dependency_job_id":"4f845c60-511e-4ec9-8dfa-917597ab76c1","html_url":"https://github.com/exonos/writer-api","commit_stats":null,"previous_names":["exonos/writer-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonos%2Fwriter-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonos%2Fwriter-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonos%2Fwriter-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exonos%2Fwriter-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exonos","download_url":"https://codeload.github.com/exonos/writer-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238188557,"owners_count":19430877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","automation","contract-automation","docker","document-builder","document-generation","document-maker","docx-templates","fastapi","jinja2","lightweight-microservice","microservice","pdf-generation","python","rest-api","scalable-api","template-engine","yaml-validation"],"created_at":"2025-02-10T21:08:29.697Z","updated_at":"2025-10-25T17:31:16.510Z","avatar_url":"https://github.com/exonos.png","language":"Python","funding_links":["https://buymeacoffee.com/exonos"],"categories":[],"sub_categories":[],"readme":"\u003ch1 style=\"max-width: 42rem; margin-bottom: 1.5rem; font-size: 2.25rem; font-weight: 800; letter-spacing: -0.025em; line-height: 1; color: #1a202c;\"\u003e\n    \u003cspan style=\"font-weight: 800;\"\u003e\n        \u003cp style=\"color: #3b82f6;\"\u003eWriter\u003cspan style=\"color: #044080;\"\u003eAPI\u003c/span\u003e\u003c/p\u003e\n    \u003c/span\u003e\n\u003c/h1\u003e\n\n## Overview\n\nThe Write API is a lightweight and scalable microservice designed to streamline the massive generation of documents via API. This project addresses a key challenge in the legal contract signing process for products offered by Apimarket, providing a seamless, automated, and secure solution to generate massive docs.\n\n### Key Features\n- **Template-Based Design**: Generate documents from `.docx`, `.md`, or `.html` templates with support for dynamic variable injection using Jinja2.\n- **YAML Configuration**: Define logic, structure, and validation rules for templates in YAML format, ensuring consistency and error prevention.\n- **Flexible Output Formats**: Supports `.docx` (default), `.pdf`, and `.html` outputs for diverse use cases.\n- **Massive Document Generation**: Optimized for high-volume operations, enabling large-scale automated workflows.\n- **Authentication**: Secure token-based authentication protects all API endpoints.\n- **Lightweight \u0026 Customizable**: No GUI ensures a lightweight design, and Docker compatibility enables easy deployment and scalability.\n- **Powerful API Ready**: Start using this project right now with the API gateway ready to use.\n\n---\n\n## Deployment Instructions\n\n### Using Docker (Recommended)\nThe easiest and most reliable way to deploy the Write API is by using Docker. Follow these steps:\n\n1. **Clone the Repository**:\n   ```bash\n   git clone https://github.com/exonos/writer-api.git\n   cd write-api\n   ```\n\n2. **Build the Docker Image**:\n   ```bash\n   docker-compose build --no-cache\n   ```\n\n3. **Start the Service**:\n   ```bash\n   docker-compose up\n   ```\n\n4. **Access the API**:\n   The API will be available at `http://localhost:8007`. Adjust the port in the `docker-compose.yml` file if needed.\n\n5. **Stop the Service**:\n   To stop the service, run:\n   ```bash\n   docker-compose down\n   ```\n\n---\n\n## Authentication\nThe Write API uses a secure token-based authentication system to protect its endpoints.\n\n### Obtaining an API Token\n1. Sign up using the `/auth/signup` endpoint.\n2. Log in with your credentials at `/auth/login` to receive an access token.\n\n### Using the Token\nInclude the token in the `Authorization` header of your HTTP requests as a Bearer token:\n\n#### Example with `curl`:\n```bash\ncurl -H \"Authorization: Bearer \u003cyour_api_token\u003e\" \\\n     http://localhost/document-templates/{template_id}/parameters\n```\n\n#### Example with Python:\n```python\nimport requests\nheaders = {'Authorization': 'Bearer \u003cyour_api_token\u003e'}\nresponse = requests.get('http://localhost/document-templates/{template_id}/parameters', headers=headers)\nif response.status_code == 200:\n    print(response.json())\nelse:\n    print(f\"Error: {response.text}\")\n```\n\n---\n\n## Parameters Section\n\n### Overview\nThe Parameters Section provides essential details about the inputs required for document generation. These parameters are defined in the YAML configuration associated with each template.\n\n### Structure\nEach parameter includes:\n- **`name`**: The name of the variable.\n- **`type`**: The expected data type (`string`, `int`, `date`, etc.).\n- **`required`**: Indicates whether the parameter is mandatory or optional.\n\n#### Example:\n```json\n[\n  {\n    \"name\": \"usuario\",\n    \"type\": \"string\",\n    \"required\": true\n  },\n  {\n    \"name\": \"fecha\",\n    \"type\": \"date\",\n    \"required\": true\n  }\n]\n```\n\n### Accessing Parameters\nTo retrieve the required parameters for a specific template, use the `/document-templates/{template_id}/parameters` endpoint.\n\n---\n\n## Document Generation\n\n### Overview\nThe **Document Generation Section** enables users to create highly customized documents from predefined templates, leveraging Jinja2 for variable injection.\n\n### Supported Template Formats\n- **`.docx`**: Ideal for editable documents.\n- **`.md`**: Markdown templates for simple and structured content.\n- **`.html`**: Templates for web-based content.\n\n### Variable Format\nTo ensure variables are recognized by Jinja2, use the following syntax in templates:\n```plaintext\n{{ variable_name }}\n```\n#### Example:\n```plaintext\nHello, {{ user_name }}! Your contract starts on {{ start_date }}.\n```\n\n### YAML Validation\nThe variables in the template must match those defined in the associated YAML configuration. The API:\n1. Validates the input data against the YAML configuration.\n2. Ensures all required variables are provided and meet the expected format.\n3. Returns an error if any required variable is missing or mismatched.\n\n### Output Formats\n- **DOCX**: The default format if none is specified.\n- **PDF**: For finalized, non-editable documents.\n- **HTML**: Web-based formats when needed.\n\n### Example Requests\n#### Generating a Document (JSON Body)\n```bash\ncurl --location 'http://localhost:8007/document-templates/{template_id}/generate' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer \u003cyour_api_token\u003e' \\\n--data '{\n  \"usuario\": \"Juan Pérez\",\n  \"razon_social\": \"COCA COLA COMPANY S.A. DE C.V.\",\n  \"fecha\": \"2025-01-16\"\n}'\n```\n\n---\n\n## Roadmap\n\n### Pending Features\n1. **Public URL for Generated Documents**:\n    - Generate a public, time-signed cryptographic URL for accessing documents.\n    - Ensure time-based expiration for secure access.\n\n2. **Database Integration**:\n    - Implement relational database tables to enable scaling as a SaaS.\n    - Store relationships between YAML files, templates, and user data.\n\n3. **Upload and Validation Endpoints**:\n    - Extend current upload functionality to support uploading templates (`.docx`, `.md`, `.html`).\n    - Validate the association between uploaded templates and YAML logic before saving.\n\n4. **Document Retrieval by User**:\n    - Create endpoints to retrieve generated documents for each user.\n    - Provide access to available templates per user.\n\n5. **Team Features**:\n    - Implement functionality for managing teams within the API.\n    - Allow team-based access to templates and generated documents.\n\n6. **Unique Token Authentication**:\n    - Introduce single-use tokens for simplified integrations.\n    - Avoid sharing permanent API keys for enhanced security.\n    - Eliminate session renewal requirements for password-based JWT authentication.\n\n7. **Permission Management**:\n    - Develop a granular permission system.\n    - Define access control for users and tokens, limiting their scope to specific actions or templates.\n\n---\n\n## Contribution\n1. Fork the repository.\n2. Create a feature branch.\n3. Submit a pull request with detailed changes.\n\nFor questions, feel free to create an issue in the repository.\n\n---\n\n## Security Vulnerabilities\n\nIf you discover a security vulnerability in Livewirestack, please help us maintain the security of this project by responsibly disclosing it to us. To report a security vulnerability, please send an email to [hh.abdiel@gmail.com](mailto:hh.abdiel@gmail.com). We'll address the issue as promptly as possible.\n\n## Credits\n\n- [Abdiel Hernandez](https://github.com/exonos)\n\n## Support My Work\n\nIf you find Livewirestack helpful and would like to support my work, you can buy me a coffee. Your support will help keep this project alive and thriving. It's a small token of appreciation that goes a long way.\n\n[![Buy me a coffee](https://cdn.buymeacoffee.com/buttons/default-orange.png)](https://buymeacoffee.com/exonos)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e \u003cb\u003eMade with ❤️ from Mexico\u003c/b\u003e \u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexonos%2Fwriter-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexonos%2Fwriter-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexonos%2Fwriter-api/lists"}