opentextsummaries/README.md

<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>

<p align="center">
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
</p>

## Open Text Summaries API

### Sitemap
- Endpoint: GET /sitemap.xml
- Description: Returns an XML sitemap including homepage, static pages (/about, /privacy, /terms, /contact), index pages (/books, /categories), and all book detail pages.
- How to submit to Google: In Google Search Console, add your property (domain) and submit the sitemap URL, e.g., https://your-domain.com/sitemap.xml

This API lets you ingest Books (with optional Category and Summary) in a create-or-update (upsert) fashion. It is designed so your client can safely resend the same data without creating duplicates.

- Method and route: POST /api/ingest/books
- Content-Type: application/json
- Authentication: none (development default). If you expose this API publicly, add auth/rate limit yourself.
- Base URL (local):
  - php artisan serve → http://127.0.0.1:8000
  - Laravel Sail/Docker → depends on your setup (often http://localhost)

What the endpoint does
- Finds or creates Category by slug or name; updates name/description if provided.
- Finds or creates Book by slug (preferred) or by the (title + author) pair; updates fields if provided.
- Finds or creates Summary by book_id; updates fields if provided.
- Processes one or many items in a single request.

Accepted request shapes
1) Single object (a single book):
{
  "title": "Clean Code",
  "author": "Robert C. Martin",
  "description": "A Handbook of Agile Software Craftsmanship",
  "publication_date": "2008-08-11",
  "cover_image": "https://example.com/cleancode.jpg",
  "slug": "clean-code",               // optional; auto-slugified from title if missing
  "category": {                        // optional
    "name": "Software Engineering",
    "slug": "software-engineering",  // optional; auto from name if missing
    "description": "SE books"
  },
  "summary": {                         // optional
    "content": "Clean Code explains principles and best practices for writing maintainable code...",
    "key_insights": "SOLID; meaningful names; small functions"
  }
}

2) Batch object with books array:
{
  "books": [
    { "title": "Clean Code", "author": "Robert C. Martin", "category": {"name": "Software Engineering"} },
    { "title": "The Pragmatic Programmer", "author": "Andrew Hunt", "summary": {"content": "..."} }
  ]
}

3) Raw JSON array (also accepted):
[
  { "title": "Clean Code", "author": "Robert C. Martin" },
  { "title": "Refactoring", "author": "Martin Fowler" }
]

Field reference
- Book
  - title (string, required)
  - author (string, required if `authors` not provided)
  - authors (array<string>, optional; preferred. If provided, `author` may be omitted. The first name is also stored in the legacy `author` field for backward compatibility.)
  - slug (string, optional; defaults to slugified title)
  - description (string, optional)
  - publication_date (YYYY-MM-DD string, optional)
  - cover_image (string URL, optional)
  - category_id (integer, optional; used if you already know an existing category ID)
  - category (object, optional; see below). If both category and category_id are provided, category takes precedence.
- Category
  - name (string, recommended if creating)
  - slug (string, optional; defaults to slugified name)
  - description (string, optional)
- Summary
  - content (string, recommended if creating a summary)
  - key_insights (string, optional)

Upsert rules (idempotency)
- Category: matched by slug if present; else by name. If found, it is updated with any provided fields. If not found, it is created.
- Book: matched by slug if present; else by composite (title + author). If found, it is updated with provided fields. If not found, it is created. If category is provided, the book's category_id is set/updated.
- Summary: matched by book_id (exactly one per book). If found, it is updated; else created.

HTTP status codes
- 200 OK: Request processed; see per-item statuses in results.
- 422 Unprocessable Entity: No valid books provided (e.g., empty payload); message explains the reason.

Example cURL (single)
curl -X POST "http://127.0.0.1:8000/api/ingest/books" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Clean Code",
        "author": "Robert C. Martin",
        "description": "A Handbook of Agile Software Craftsmanship",
        "publication_date": "2008-08-11",
        "cover_image": "https://example.com/cleancode.jpg",
        "category": {"name": "Software Engineering", "description": "SE books"},
        "summary": {"content": "...", "key_insights": "..."}
      }'

Example success response (single)
{
  "results": [
    {
      "book": {"status": "created", "id": 12, "slug": "clean-code"},
      "category": {"status": "created", "id": 4, "slug": "software-engineering"},
      "summary": {"status": "created", "id": 9}
    }
  ]
}

Example cURL (batch)
curl -X POST "http://127.0.0.1:8000/api/ingest/books" \
  -H "Content-Type: application/json" \
  -d '{
        "books": [
          {"title": "Clean Code", "author": "Robert C. Martin", "category": {"name": "Software Engineering"}},
          {"title": "The Pragmatic Programmer", "author": "Andrew Hunt", "summary": {"content": "..."}},
          {"author": "Missing Title"}
        ]
      }'

Example mixed response (batch with one error)
{
  "results": [
    {
      "book": {"status": "updated", "id": 12, "slug": "clean-code"},
      "category": {"status": "updated", "id": 4, "slug": "software-engineering"},
      "summary": null
    },
    {
      "book": {"status": "created", "id": 13, "slug": "the-pragmatic-programmer"},
      "category": null,
      "summary": {"status": "created", "id": 10}
    },
    {
      "index": 2,
      "status": "error",
      "message": "title and author are required."
    }
  ]
}

Example error (empty payload)
Status: 422
{
  "message": "No books provided."
}

Notes
- Authors are normalized to a separate `authors` table and linked via a pivot. You may send `author` (string) or `authors` (array). If `authors` is provided, the first name is also saved to the legacy `author` column on books for compatibility.
- This endpoint performs minimal validation: each item must have title and author/authors. Other fields are optional.
- Slugs are derived from names/titles if not provided, using Laravel's Str::slug.
- There is no pagination or retrieval endpoint here; this endpoint is for ingestion only.
- No authentication/rate limiting is configured by default; add it before exposing this API to untrusted clients.

## About Laravel

Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:

- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).

Laravel is accessible, powerful, and provides tools required for large, robust applications.

## Learning Laravel

Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework.

You may also try the [Laravel Bootcamp](https://bootcamp.laravel.com), where you will be guided through building a modern Laravel application from scratch.

If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.

## Laravel Sponsors

We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).

### Premium Partners

- **[Vehikl](https://vehikl.com)**
- **[Tighten Co.](https://tighten.co)**
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
- **[64 Robots](https://64robots.com)**
- **[Curotec](https://www.curotec.com/services/technologies/laravel)**
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
- **[Redberry](https://redberry.international/laravel-development)**
- **[Active Logic](https://activelogic.com)**

## Contributing

Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).

## Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).

## Security Vulnerabilities

If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.

## License

The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).