roast-api 1.3.0 → 1.4.0

package/.github/workflows/release.yml

@@ -28,3 +28,24 @@ jobs:
           files: |
             api/client.js
             postman/roast-as-a-service.postman_collection.json
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        run: twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

package/README.md

@@ -7,6 +7,8 @@
   <img src="https://hits.sh/maijied.github.io/roast-as-a-service.svg?view=today-total&style=flat-square&label=visitors&color=ec4899&labelColor=020617" alt="Visitor Count" />
   <a href="https://www.npmjs.com/package/roast-api"><img src="https://img.shields.io/npm/v/roast-api?style=flat-square&color=f97316&labelColor=020617" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/roast-api"><img src="https://img.shields.io/npm/dm/roast-api?style=flat-square&color=ec4899&labelColor=020617" alt="npm downloads" /></a>
+  <a href="https://pypi.org/project/roast-api/"><img src="https://img.shields.io/pypi/v/roast-api?style=flat-square&color=3b82f6&labelColor=020617" alt="PyPI version" /></a>
+  <a href="https://packagist.org/packages/maizied/roast-api"><img src="https://img.shields.io/packagist/v/maizied/roast-api?style=flat-square&color=10b981&labelColor=020617" alt="Packagist version" /></a>
   <a href="https://github.com/Maijied/roast-as-a-service/actions/workflows/deploy.yml"><img src="https://github.com/Maijied/roast-as-a-service/actions/workflows/deploy.yml/badge.svg" alt="Deploy to GitHub Pages" /></a>
 </p>
 
@@ -66,7 +68,31 @@ Load the client SDK directly in your browser:
 </script>
 ```
 
-### 3. Direct Fetch
+### 3. Install via Composer (PHP)
+```bash
+composer require maizied/roast-api
+```
+
+```php
+use Maizied\RoastApi\RaaS;
+
+$roast = RaaS::getRandomRoast(['lang' => 'en']);
+echo $roast['text'];
+```
+
+### 4. Install via pip (Python)
+```bash
+pip install roast-api
+```
+
+```python
+from roast_api import get_random_roast
+
+roast = get_random_roast(lang='en')
+print(roast['text'])
+```
+
+### 5. Direct Fetch
 Or just fetch the JSON files directly:
 
 ```javascript

package/composer.json

@@ -0,0 +1,30 @@
+{
+    "name": "maizied/roast-api",
+    "description": "A PHP client for RaaS — Roast as a Service. CDN-served static JSON API for developer roasts.",
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Maizied",
+            "email": "mdshuvo40@gmail.com"
+        }
+    ],
+    "homepage": "https://maijied.github.io/roast-as-a-service/",
+    "keywords": [
+        "roast",
+        "api",
+        "developer",
+        "humor",
+        "fun",
+        "cdn"
+    ],
+    "require": {
+        "php": ">=7.4"
+    },
+    "autoload": {
+        "psr-4": {
+            "Maizied\\RoastApi\\": "src/"
+        }
+    },
+    "minimum-stability": "stable"
+}

package/index.html

@@ -53,6 +53,12 @@
                     <a href="https://www.npmjs.com/package/roast-api" target="_blank"><img
                             src="https://img.shields.io/npm/dm/roast-api?style=flat-square&color=ec4899&labelColor=020617"
                             alt="npm downloads" /></a>
+                    <a href="https://pypi.org/project/roast-api/" target="_blank"><img
+                            src="https://img.shields.io/pypi/v/roast-api?style=flat-square&color=3b82f6&labelColor=020617"
+                            alt="PyPI version" /></a>
+                    <a href="https://packagist.org/packages/maizied/roast-api" target="_blank"><img
+                            src="https://img.shields.io/packagist/v/maizied/roast-api?style=flat-square&color=10b981&labelColor=020617"
+                            alt="Packagist version" /></a>
                     <a href="https://github.com/Maijied/roast-as-a-service" target="_blank"><img
                             src="https://img.shields.io/github/stars/Maijied/roast-as-a-service?style=flat-square&color=f97316&labelColor=020617"
                             alt="GitHub stars" /></a>
@@ -163,8 +169,27 @@ RaaS.getRandomRoast({ lang: 'en' })
   RaaS.getRandomRoast({ lang: 'bn', intensity: 2 })
     .then(r =&gt; console.log(r.text));
 &lt;/script&gt;</code></pre>
+                        <div class="code-card">
+                            <h3>Composer (PHP)</h3>
+                            <pre><code>composer require maizied/roast-api
+
+// Usage
+use Maizied\RoastApi\RaaS;
+
+$roast = RaaS::getRandomRoast(['lang' =&gt; 'en']);
+echo $roast['text'];</code></pre>
+                        </div>
+                        <div class="code-card">
+                            <h3>pip (Python)</h3>
+                            <pre><code>pip install roast-api
+
+# Usage
+from roast_api import get_random_roast
+
+roast = get_random_roast(lang='en')
+print(roast['text'])</code></pre>
+                        </div>
                     </div>
-                </div>
             </section>
 
             <section class="section">

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "roast-api",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "A static JSON API for delivering developer roasts.",
     "main": "api/client.js",
     "scripts": {

package/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "roast-api"
+version = "1.4.0"
+description = "A Python client for RaaS — Roast as a Service. CDN-served static JSON API for developer roasts."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.7"
+authors = [
+    {name = "Maizied", email = "mdshuvo40@gmail.com"}
+]
+keywords = ["roast", "api", "developer", "humor", "fun", "cdn"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.20.0",
+]
+
+[project.urls]
+Homepage = "https://maijied.github.io/roast-as-a-service/"
+Repository = "https://github.com/Maijied/roast-as-a-service"
+
+[tool.setuptools.packages.find]
+include = ["roast_api*"]

package/roast_api/__init__.py

@@ -0,0 +1,29 @@
+"""
+RaaS — Roast as a Service Python Client
+
+A lightweight Python client for fetching developer roasts from the
+RaaS static JSON API hosted on GitHub Pages.
+
+Usage:
+    from roast_api import get_random_roast, get_all_roasts
+
+    roast = get_random_roast(lang='en')
+    print(roast['text'])
+"""
+
+from roast_api.client import (
+    get_random_roast,
+    get_all_roasts,
+    get_manifest,
+    get_shard,
+    clear_cache,
+)
+
+__version__ = "1.4.0"
+__all__ = [
+    "get_random_roast",
+    "get_all_roasts",
+    "get_manifest",
+    "get_shard",
+    "clear_cache",
+]

package/roast_api/client.py

@@ -0,0 +1,89 @@
+"""
+RaaS Python Client — core logic.
+
+Fetches roasts from the static JSON API on GitHub Pages,
+with in-memory caching and optional filtering.
+"""
+
+import random
+from typing import Any, Dict, List, Optional
+
+import requests
+
+BASE_URL = "https://maijied.github.io/roast-as-a-service/api"
+
+# In-memory caches
+_manifest_cache: Optional[Dict[str, Any]] = None
+_shard_cache: Dict[str, Dict[str, Any]] = {}
+
+
+def get_manifest() -> Dict[str, Any]:
+    """Fetch and cache the API manifest."""
+    global _manifest_cache
+    if _manifest_cache is not None:
+        return _manifest_cache
+
+    url = f"{BASE_URL}/manifest.json"
+    resp = requests.get(url, timeout=10)
+    resp.raise_for_status()
+    _manifest_cache = resp.json()
+    return _manifest_cache
+
+
+def get_shard(lang: str = "en", shard: int = 1) -> Dict[str, Any]:
+    """Fetch and cache a specific language shard."""
+    key = f"{lang}-{shard}"
+    if key in _shard_cache:
+        return _shard_cache[key]
+
+    url = f"{BASE_URL}/{lang}/roasts-{lang}-{shard}.json"
+    resp = requests.get(url, timeout=10)
+    resp.raise_for_status()
+    _shard_cache[key] = resp.json()
+    return _shard_cache[key]
+
+
+def get_random_roast(
+    lang: str = "en",
+    intensity: Optional[int] = None,
+    max_length: Optional[int] = None,
+) -> Dict[str, Any]:
+    """
+    Get a random roast.
+
+    Args:
+        lang: Language code ('en' or 'bn'). Default: 'en'.
+        intensity: Filter by intensity (1–3). Default: None (any).
+        max_length: Maximum text length. Default: None (any).
+
+    Returns:
+        A dict with keys: id, text, intensity, length.
+
+    Raises:
+        ValueError: If no roasts match the given filters.
+    """
+    data = get_shard(lang)
+    roasts: List[Dict[str, Any]] = data.get("roasts", [])
+
+    if intensity is not None:
+        roasts = [r for r in roasts if r.get("intensity") == intensity]
+    if max_length is not None:
+        roasts = [r for r in roasts if r.get("length", 0) <= max_length]
+
+    if not roasts:
+        raise ValueError("No roasts match the given filters.")
+
+    return random.choice(roasts)
+
+
+def get_all_roasts(lang: str = "en") -> List[Dict[str, Any]]:
+    """Get all roasts for a language."""
+    data = get_shard(lang)
+    return data.get("roasts", [])
+
+
+def clear_cache() -> None:
+    """Clear the in-memory caches."""
+    global _manifest_cache, _shard_cache
+    _manifest_cache = None
+    _shard_cache = {}

package/src/RaaS.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace Maizied\RoastApi;
+
+/**
+ * RaaS — Roast as a Service PHP Client
+ *
+ * A lightweight PHP client for fetching developer roasts from the
+ * RaaS static JSON API hosted on GitHub Pages.
+ *
+ * @package maizied/roast-api
+ * @author  Maizied <mdshuvo40@gmail.com>
+ * @license MIT
+ * @link    https://maijied.github.io/roast-as-a-service/
+ */
+class RaaS
+{
+    private const BASE_URL = 'https://maijied.github.io/roast-as-a-service/api';
+
+    /** @var array|null In-memory manifest cache */
+    private static ?array $manifestCache = null;
+
+    /** @var array<string, array> In-memory shard cache */
+    private static array $shardCache = [];
+
+    /**
+     * Fetch the API manifest.
+     *
+     * @return array Decoded manifest data
+     * @throws \RuntimeException If the fetch fails
+     */
+    public static function getManifest(): array
+    {
+        if (self::$manifestCache !== null) {
+            return self::$manifestCache;
+        }
+
+        $url = self::BASE_URL . '/manifest.json';
+        $json = @file_get_contents($url);
+
+        if ($json === false) {
+            throw new \RuntimeException("Failed to fetch manifest from {$url}");
+        }
+
+        self::$manifestCache = json_decode($json, true);
+        return self::$manifestCache;
+    }
+
+    /**
+     * Fetch a specific shard.
+     *
+     * @param string $lang  Language code (e.g., 'en', 'bn')
+     * @param int    $shard Shard number (default: 1)
+     * @return array Decoded shard data
+     * @throws \RuntimeException If the fetch fails
+     */
+    public static function getShard(string $lang = 'en', int $shard = 1): array
+    {
+        $key = "{$lang}-{$shard}";
+
+        if (isset(self::$shardCache[$key])) {
+            return self::$shardCache[$key];
+        }
+
+        $url = self::BASE_URL . "/{$lang}/roasts-{$lang}-{$shard}.json";
+        $json = @file_get_contents($url);
+
+        if ($json === false) {
+            throw new \RuntimeException("Failed to fetch shard from {$url}");
+        }
+
+        self::$shardCache[$key] = json_decode($json, true);
+        return self::$shardCache[$key];
+    }
+
+    /**
+     * Get a random roast.
+     *
+     * @param array $options {
+     *     @type string $lang      Language code ('en' or 'bn'). Default: 'en'.
+     *     @type int    $intensity Filter by intensity (1–3). Default: null (any).
+     *     @type int    $maxLength Maximum text length. Default: null (any).
+     * }
+     * @return array Roast object with keys: id, text, intensity, length
+     * @throws \RuntimeException If fetch fails or no roasts match filters
+     */
+    public static function getRandomRoast(array $options = []): array
+    {
+        $lang = $options['lang'] ?? 'en';
+        $intensity = $options['intensity'] ?? null;
+        $maxLength = $options['maxLength'] ?? null;
+
+        $shard = self::getShard($lang);
+        $roasts = $shard['roasts'] ?? [];
+
+        // Apply filters
+        if ($intensity !== null) {
+            $roasts = array_filter($roasts, fn($r) => ($r['intensity'] ?? 0) === $intensity);
+        }
+        if ($maxLength !== null) {
+            $roasts = array_filter($roasts, fn($r) => ($r['length'] ?? 0) <= $maxLength);
+        }
+
+        $roasts = array_values($roasts);
+
+        if (empty($roasts)) {
+            throw new \RuntimeException('No roasts match the given filters.');
+        }
+
+        return $roasts[array_rand($roasts)];
+    }
+
+    /**
+     * Get all roasts for a language.
+     *
+     * @param string $lang Language code. Default: 'en'.
+     * @return array List of roast objects
+     */
+    public static function getAllRoasts(string $lang = 'en'): array
+    {
+        $shard = self::getShard($lang);
+        return $shard['roasts'] ?? [];
+    }
+
+    /**
+     * Clear the in-memory cache.
+     */
+    public static function clearCache(): void
+    {
+        self::$manifestCache = null;
+        self::$shardCache = [];
+    }
+}