gr_api_manager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5f6ec1afb3c1aed64ba13f1d41198f656b52918b061bb0e9fffbb28145ec681
+  data.tar.gz: eb578c753e0a5f662dcdc5198855e3f063c6241d3b41f531e3eaaebfb2c66dd4
+SHA512:
+  metadata.gz: 840d926e759021f66b36e4148a41dc46a6e26bc74aad62aeab1cfef669620dcb3f344febba2bfe3ed287568844c141b92e3004e193d90d2c9d3d95faa117aa7d
+  data.tar.gz: 3e65530682e1ae7bded34147ef2df0f75e345bcaf702ed46f54d59fb746ed373d2e1d59344be796723f26af3c8cb26db54cdb42cee2a940c70b9cdd4b983aad7

data/README.md

@@ -0,0 +1,345 @@
+# GR API Manager
+
+[![Gem Version](https://badge.fury.io/rb/gr-api-manager.svg)](https://rubygems.org/gems/gr-api-manager)
+
+A minimal, opinionated Ruby wrapper around Sinatra that eliminates boilerplate from REST API development. Authentication, parameter validation, type casting, CORS, and error handling are handled at the framework level — you write only the business logic.
+
+---
+
+## Features
+
+- **Available on RubyGems!** Install globally and use it in any project.
+- Route-level Bearer Token authentication (opt-in/opt-out per endpoint).
+- Declarative required parameter validation with automatic `400 Bad Request` responses.
+- Smart type casting for query string values (`"10"` -> `Integer`, `"true"` -> `TrueClass`, `"9.5"` -> `Float`).
+- Global JSON error responses for `404` and `500`.
+- Broad CORS and `OPTIONS` preflight handling out of the box (Frontend ready).
+- API versioning via configurable route prefix (e.g. `/api/v1`).
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'gr-api-manager'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+Or install it yourself directly via RubyGems:
+```bash
+gem install gr-api-manager
+```
+
+---
+
+## Quick Start
+
+```ruby
+require 'gr_api_manager'
+
+api = GRApiManager::Server.new(
+  port: 4567,
+  bearer_token: "your_secret_token",
+  prefix: "/api/v1"
+)
+
+# Public endpoint
+api.get('/health', auth: false) do
+  { status: 'online', time: Time.now.to_s }
+end
+
+api.run!
+```
+
+```bash
+curl http://localhost:4567/api/v1/health
+# => {"status":"online","time":"..."}
+```
+
+---
+
+## Configuration
+
+All parameters are optional. If omitted, the manager falls back to environment variables loaded from a `.env` file at the project root (via `dotenv`). If neither is provided, defaults are used.
+
+```ruby
+GRApiManager::Server.new(
+  port: 4567,                        # Default: ENV['PORT'] || 4000
+  bearer_token: "secret",            # Default: ENV['API_TOKEN']
+  permitted_hosts: ["example.com"],  # Host allowlist — empty means allow all
+  prefix: "/api/v1"                  # Route prefix applied to all endpoints
+)
+```
+
+### Using a .env file (Recommended)
+
+Create a `.env` file at the root of your project:
+
+```env
+PORT=4567
+API_TOKEN=your_secret_token
+```
+
+Then initialize the manager with no arguments and it will pick everything up automatically:
+
+```ruby
+require 'gr_api_manager'
+
+api = GRApiManager::Server.new
+# Reads PORT and API_TOKEN from .env
+```
+
+This is the recommended approach for production — keep secrets out of source code and out of version control. Add `.env` to your `.gitignore`.
+
+```text
+# .gitignore
+.env
+```
+
+### Priority order
+
+When a value is provided both in code and in `.env`, the explicit argument always wins:
+
+```text
+new(bearer_token: "hardcoded")  >  ENV['API_TOKEN']  >  nil (auth disabled)
+new(port: 4567)                 >  ENV['PORT']        >  4000
+```
+
+---
+
+## Defining Routes
+
+The manager exposes `get`, `post`, `put`, and `delete` methods. Each route receives a merged `params` hash containing both URL/query parameters (type-cast) and the parsed JSON body.
+
+```ruby
+api.get('/users', auth: true, requires: [:role, :age]) do |params|
+  # params is a merged, type-cast hash of all inputs
+  { 
+    requested_role: params[:role],
+    is_adult: params[:age] >= 18 # age is safely cast to Integer
+  }
+end
+```
+
+### Options
+
+| Option     | Type    | Default | Description                                      |
+|------------|---------|---------|--------------------------------------------------|
+| `auth`     | Boolean | `true`  | Require Bearer Token for this route              |
+| `requires` | Array   | `[]`    | List of required parameter keys (symbols/strings)|
+
+---
+
+## Authentication
+
+All routes require a valid Bearer Token by default. Pass the token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer your_secret_token" http://localhost:4567/api/v1/users
+```
+
+To make a route public, set `auth: false`:
+
+```ruby
+api.get('/health', auth: false) do
+  { status: 'online' }
+end
+```
+
+**Automatic Error Responses:**
+
+```json
+// Missing header (401)
+{ "error": "Token required. Format: 'Bearer <token>'" }
+
+// Wrong token (403)
+{ "error": "Invalid token" }
+```
+
+---
+
+## Parameter Validation
+
+Declare required parameters at the route level. If any are missing or blank, the framework responds with `400 Bad Request` automatically — no conditional logic needed in your handler.
+
+```ruby
+api.post('/users', requires: [:name, :email]) do |params|
+  status 201
+  { message: "User created", user: params }
+end
+```
+
+```bash
+curl -X POST http://localhost:4567/api/v1/users \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Gabo"}'
+
+# => 400 { "error": "Missing required parameters", "required": ["email"] }
+```
+
+---
+
+## Smart Type Casting
+
+Query string parameters are automatically cast to native Ruby types before reaching your handler.
+
+| Input string | Ruby type | Value    |
+|--------------|-----------|----------|
+| `"42"`       | Integer   | `42`     |
+| `"3.14"`     | Float     | `3.14`   |
+| `"true"`     | TrueClass | `true`   |
+| `"false"`    | FalseClass| `false`  |
+| `"hello"`    | String    | `"hello"`|
+
+```bash
+curl "http://localhost:4567/api/v1/test/types?age=18&active=true&score=9.5" \
+  -H "Authorization: Bearer secret"
+
+# => { "age": 18, "active": true, "score": 9.5 }
+```
+
+---
+
+## Error Handling
+
+Global handlers return consistent JSON for unmatched routes and unhandled exceptions.
+
+```json
+// 404
+{ "error": "Endpoint not found", "path": "/api/v1/missing" }
+
+// 500
+{ "error": "Internal Server Error", "details": "..." }
+```
+
+You can also set status codes and short-circuit responses manually inside any handler:
+
+```ruby
+api.get('/users/:id') do |params|
+  if params[:id] == 0
+    status 404
+    next { error: "Invalid user ID" }
+  end
+
+  { id: params[:id], name: "User_#{params[:id]}" }
+end
+```
+
+---
+
+## Request Logging
+
+Every request is logged to stdout with a timestamp and color-coded status:
+
+```text
+[14:32:01] GET /api/v1/health - 200
+[14:32:05] POST /api/v1/users - 400
+```
+
+Green for 2xx, red for everything else.
+
+---
+
+## Running the Server
+
+```ruby
+api.run!
+```
+
+```text
+=============================================
+  GR API MANAGER STARTED
+  Port   : 4567
+  Auth   : Enabled
+  Prefix : /api/v1
+=============================================
+```
+
+---
+
+## Full Usage Example
+
+Below is a complete working API covering the most common patterns.
+
+```ruby
+require 'gr_api_manager'
+
+api = GRApiManager::Server.new(
+  port: 4567,
+  bearer_token: "secret123",
+  prefix: "/api/v1"
+)
+
+# 1. Public health check — no token required
+api.get('/health', auth: false) do
+  { status: 'online', time: Time.now.strftime("%Y-%m-%d %H:%M:%S") }
+end
+
+# 2. List users — token required (default)
+api.get('/users') do |params|
+  users = [
+    { id: 1, name: "Alice", role: "admin" },
+    { id: 2, name: "Bob",   role: "viewer" }
+  ]
+  { users: users, total: users.length }
+end
+
+# 3. Get single user by ID — :id is cast to Integer automatically
+api.get('/users/:id') do |params|
+  if params[:id] == 0
+    status 404
+    next { error: "User not found" }
+  end
+  { id: params[:id], name: "User_#{params[:id]}" }
+end
+
+# 4. Create user — validates required fields before reaching the block
+api.post('/users', requires: [:name, :role]) do |params|
+  status 201
+  { message: "User created", user: { name: params[:name], role: params[:role] } }
+end
+
+# 5. Update user
+api.put('/users/:id', requires: [:name]) do |params|
+  { message: "User #{params[:id]} updated", name: params[:name] }
+end
+
+# 6. Delete user
+api.delete('/users/:id') do |params|
+  { message: "User #{params[:id]} deleted" }
+end
+
+api.run!
+```
+
+### Minimal setup using only .env
+
+```env
+# .env
+PORT=4567
+API_TOKEN=secret123
+```
+
+```ruby
+# api_server.rb
+require 'gr_api_manager'
+
+api = GRApiManager::Server.new  # reads everything from .env
+
+api.get('/ping', auth: false) { { pong: true } }
+
+api.run!
+```
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/gr_api_manager.rb

@@ -0,0 +1,149 @@
+require 'sinatra/base'
+require 'json'
+require 'dotenv/load'
+
+module GRApiManager
+  class Server
+    attr_reader :app_class
+
+    # Initializes the server configuration.
+    def initialize(port: nil, bearer_token: nil, permitted_hosts: [], prefix: '')
+      @port = port || ENV['PORT'] || 4000
+      @token = bearer_token || ENV['API_TOKEN']
+      @permitted_hosts = permitted_hosts.empty? ? [] : permitted_hosts
+      @prefix = prefix
+      
+      @app_class = Class.new(Sinatra::Base) do
+        
+        # Logs HTTP requests with status-based color coding.
+        def log_request(method, path, params, status_code)
+          color = status_code.between?(200, 299) ? "\e[32m" : "\e[31m"
+          puts "[#{Time.now.strftime('%H:%M:%S')}] #{color}#{method} #{path} - #{status_code}\e[0m"
+        end
+
+        # Casts string URL parameters to native Ruby types (Integer, Float, Boolean).
+        def smart_parse(hash)
+          hash.transform_values do |val|
+            case val
+            when 'true' then true
+            when 'false' then false
+            when /^[0-9]+$/ then val.to_i
+            when /^[0-9]+\.[0-9]+$/ then val.to_f
+            else val
+            end
+          end
+        end
+      end
+
+      configure_app
+    end
+
+    private
+
+    # Sets up Sinatra environment, CORS policies, and global error handlers.
+    def configure_app
+      app = @app_class
+      app.set :port, @port
+      app.set :bind, '0.0.0.0'
+      app.set :token, @token
+      app.set :show_exceptions, false 
+      app.set :host_authorization, { permitted_hosts: @permitted_hosts }
+
+      # Enable broad CORS and handle preflight requests.
+      app.before do
+        headers 'Access-Control-Allow-Origin' => '*',
+                'Access-Control-Allow-Methods' => 'GET, POST, PUT, DELETE, OPTIONS',
+                'Access-Control-Allow-Headers' => 'Content-Type, Authorization'
+        content_type :json
+      end
+
+      app.options '*' do
+        halt 200
+      end
+
+      # JSON formatted 404 response.
+      app.not_found do
+        status 404
+        { error: "Endpoint not found", path: request.path_info }.to_json
+      end
+
+      # JSON formatted 500 response.
+      app.error do
+        e = env['sinatra.error']
+        status 500
+        { error: "Internal Server Error", details: e.message }.to_json
+      end
+    end
+
+    public
+
+    # Dynamically generate routing methods (get, post, put, delete).
+    %w[get post put delete].each do |verb|
+      define_method(verb) do |path, options = {}, &block|
+        register_route(verb, path, options, &block)
+      end
+    end
+
+    # Core routing logic: auth validation, param parsing, and block execution.
+    def register_route(verb, path, options = {}, &block)
+      verb = verb.to_s.upcase
+      require_auth = options.fetch(:auth, true)
+      required_params = options.fetch(:requires, [])
+      
+      # Construct the full path with the optional prefix.
+      full_path = File.join('/', @prefix.to_s, path.to_s).gsub(%r{/+}, '/')
+
+      handler = proc do
+        
+        # 1. Authentication check
+        if require_auth
+          auth_header = request.env["HTTP_AUTHORIZATION"]
+          halt 401, { error: "Token required. Format: 'Bearer <token>'" }.to_json if auth_header.nil?
+          halt 403, { error: "Invalid token" }.to_json if auth_header.split(" ").last != settings.token
+        end
+
+        # 2. Body parsing (for POST/PUT requests)
+        parsed_body = {}
+        if ['POST', 'PUT'].include?(verb)
+          body_data = request.body.read.to_s
+          unless body_data.empty?
+            begin
+              parsed_body = JSON.parse(body_data, symbolize_names: true)
+            rescue JSON::ParserError
+              halt 400, { error: "Invalid JSON body" }.to_json
+            end
+          end
+        end
+
+        # 3. Merge query parameters with parsed JSON body
+        all_params = smart_parse(params).merge(parsed_body)
+
+        # 4. Declarative parameter validation
+        missing = required_params.select { |p| all_params[p.to_sym].nil? || all_params[p.to_sym].to_s.strip.empty? }
+        if missing.any?
+          status 400
+          log_request(verb, full_path, all_params, 400)
+          next { error: "Missing required parameters", required: missing }.to_json
+        end
+
+        # 5. Execute user-defined block
+        result = instance_exec(all_params, &block)
+        log_request(verb, full_path, all_params, response.status)
+        result.to_json
+      end
+
+      @app_class.send(verb.downcase, full_path, &handler)
+    end
+
+    # Starts the Sinatra server with a custom GR banner.
+    def run!
+      puts "============================================="
+      puts "  GR API MANAGER STARTED"
+      puts "  Port   : #{@port}"
+      puts "  Auth   : #{@token ? 'Enabled' : 'Public'}"
+      puts "  Prefix : #{@prefix.empty? ? '/' : @prefix}"
+      puts "============================================="
+      @app_class.run!
+    end
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: gr_api_manager
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Razo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: Eliminates boilerplate from REST API development. Handles Auth, CORS,
+  parameter validation, and type casting.
+email:
+- garabatoangelopolis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/gr_api_manager.rb
+homepage: https://github.com/Gabo-Razo/sinatra-api-manager
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/Gabo-Razo/sinatra-api-manager
+  changelog_uri: https://github.com/Gabo-Razo/sinatra-api-manager/blob/main/README.md
+post_install_message: Thanks for installing GR API Manager! Ready to eliminate boilerplate?
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A minimal, opinionated Ruby wrapper around Sinatra.
+test_files: []