chadstart 1.0.0

package/docs/stylesheets/extra.css

@@ -0,0 +1,375 @@
+/* ============================================================
+   Landing page hero section
+   ============================================================ */
+
+.mdx-container {
+  padding-top: 1rem;
+  position: relative;
+  overflow: hidden;
+  background: linear-gradient(
+    to bottom,
+    var(--md-primary-fg-color),
+    hsla(var(--md-hue), 15%, 21%, 1) 99%,
+    var(--md-default-bg-color) 99%
+  );
+}
+
+/* ── Tech grid background overlay ── */
+.mdx-tech-bg {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+  background-image:
+    linear-gradient(rgba(255, 255, 255, 0.04) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.04) 1px, transparent 1px);
+  background-size: 40px 40px;
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0%,
+    rgba(0, 0, 0, 0.6) 15%,
+    rgba(0, 0, 0, 0.6) 85%,
+    transparent 100%
+  );
+}
+
+/* ── Floating warrior mascots (parallax) ── */
+.mdx-mascot {
+  position: absolute;
+  bottom: 0;
+  z-index: 1;
+  pointer-events: none;
+  user-select: none;
+}
+
+.mdx-mascot img {
+  width: 200px;
+  height: auto;
+  filter: drop-shadow(0 8px 24px rgba(0, 0, 0, 0.5));
+  animation: mdx-mascot-float 6s ease-in-out infinite;
+}
+
+.mdx-mascot--left {
+  left: 0;
+}
+
+.mdx-mascot--right {
+  right: 0;
+  animation-delay: -3s;
+}
+
+.mdx-mascot--right img {
+  animation-delay: -3s;
+}
+
+@keyframes mdx-mascot-float {
+  0%,  100% { transform: translateY(0px)   rotate(-1.5deg); }
+  50%        { transform: translateY(-18px) rotate(1.5deg);  }
+}
+
+@media screen and (max-width: 96em) {
+  .mdx-mascot { display: none; }
+}
+
+.mdx-hero {
+  position: relative;
+  z-index: 2;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 3rem;
+  align-items: center;
+  padding: 4rem 0 5rem;
+  color: var(--md-primary-bg-color);
+}
+
+@media screen and (max-width: 76.25em) {
+  .mdx-hero {
+    grid-template-columns: 1fr;
+    text-align: center;
+  }
+
+  .mdx-hero__code {
+    display: none;
+  }
+}
+
+.mdx-hero h1 {
+  font-size: 2.8rem;
+  font-weight: 700;
+  line-height: 1.2;
+  color: var(--md-primary-bg-color);
+  margin-bottom: 1rem;
+}
+
+.mdx-hero__accent {
+  /* subtle fade on the second heading line for visual layering */
+  opacity: 0.85;
+}
+
+.mdx-hero__description {
+  font-size: 1.15rem;
+  line-height: 1.7;
+  opacity: 0.9;
+  margin-bottom: 2rem;
+  max-width: 480px;
+}
+
+@media screen and (max-width: 76.25em) {
+  .mdx-hero__description {
+    max-width: 100%;
+  }
+}
+
+/* Code block in hero */
+.mdx-hero__code {
+  background-color: hsla(0, 0%, 0%, 0.4);
+  border-radius: 0.5rem;
+  padding: 1.5rem;
+  overflow: auto;
+}
+
+.mdx-hero__code pre {
+  margin: 0;
+  background: transparent;
+  padding: 0;
+  overflow: visible;
+}
+
+.mdx-hero__code code {
+  font-size: 0.85rem;
+  line-height: 1.7;
+  color: #e0e0e0;
+}
+
+/* YAML syntax highlighting colours in hero */
+.mdx-hero__code .nc { color: #82b1ff; font-weight: 600; }
+.mdx-hero__code .na { color: #80cbc4; }
+.mdx-hero__code .s  { color: #c3e88d; }
+.mdx-hero__code .kc { color: #f78c6c; }
+.mdx-hero__code .m  { color: #f78c6c; }
+
+/* ============================================================
+   CTA buttons — colourful spinning border animation
+   (inspired by coding2go.com/border-animation/)
+   ============================================================ */
+
+.mdx-cta-group {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  margin-top: 1.5rem;
+}
+
+@media screen and (max-width: 76.25em) {
+  .mdx-cta-group {
+    justify-content: center;
+  }
+}
+
+.mdx-cta {
+  position: relative;
+  z-index: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4em;
+  padding: 0.7em 1.7em;
+  border-radius: 0.4rem;
+  font-size: 0.9rem;
+  font-weight: 600;
+  text-decoration: none;
+  cursor: pointer;
+  overflow: hidden;
+  transition: transform 0.2s, opacity 0.2s;
+  white-space: nowrap;
+}
+
+.mdx-cta:hover {
+  transform: translateY(-2px);
+  opacity: 0.92;
+  text-decoration: none;
+}
+
+/* Spinning conic-gradient that forms the animated border */
+.mdx-cta::before {
+  content: '';
+  position: absolute;
+  z-index: -2;
+  left: -50%;
+  top: -50%;
+  width: 200%;
+  height: 200%;
+  background: conic-gradient(
+    #ff0080,
+    #ff8c00,
+    #ffe600,
+    #00ff80,
+    #00cfff,
+    #7b2fff,
+    #ff0080
+  );
+  animation: mdx-cta-border-spin 3s linear infinite;
+}
+
+/* Inner fill — hides the gradient except at the border edges */
+.mdx-cta::after {
+  content: '';
+  position: absolute;
+  z-index: -1;
+  inset: 3px;
+  border-radius: calc(0.4rem - 3px);
+}
+
+@keyframes mdx-cta-border-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Primary: white fill */
+.mdx-cta--primary {
+  color: var(--md-primary-fg-color);
+}
+.mdx-cta--primary::after {
+  background: #fff;
+}
+.mdx-cta--primary span {
+  color: var(--md-primary-fg-color);
+  font-weight: 700;
+}
+
+/* Ghost: dark fill */
+.mdx-cta--ghost {
+  color: var(--md-primary-bg-color);
+}
+.mdx-cta--ghost::after {
+  background: hsla(var(--md-hue), 25%, 18%, 0.95);
+}
+.mdx-cta--ghost span,
+.mdx-cta--ghost svg {
+  color: var(--md-primary-bg-color);
+  fill: var(--md-primary-bg-color);
+}
+
+.mdx-cta svg {
+  width: 1em;
+  height: 1em;
+  fill: currentColor;
+}
+
+/* ============================================================
+   Getting started section
+   ============================================================ */
+
+.mdx-getting-started {
+  padding: 4rem 0;
+  background: var(--md-code-bg-color);
+  border-top: 1px solid var(--md-default-fg-color--lightest);
+  border-bottom: 1px solid var(--md-default-fg-color--lightest);
+}
+
+.mdx-section-title {
+  text-align: center;
+  font-size: 1.8rem;
+  font-weight: 700;
+  margin-bottom: 2.5rem;
+}
+
+.mdx-gs-steps {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 2rem;
+}
+
+.mdx-gs-step {
+  display: flex;
+  gap: 1rem;
+  align-items: flex-start;
+}
+
+.mdx-gs-step__num {
+  flex-shrink: 0;
+  width: 2.2rem;
+  height: 2.2rem;
+  background: var(--md-primary-fg-color);
+  color: var(--md-primary-bg-color);
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 1rem;
+}
+
+.mdx-gs-step__label {
+  font-weight: 600;
+  margin: 0 0 0.5rem;
+  font-size: 0.95rem;
+}
+
+.mdx-gs-step__code pre {
+  margin: 0 0 0.5rem;
+  border-radius: 0.3rem;
+  font-size: 0.8rem;
+}
+
+.mdx-gs-step__note {
+  display: block;
+  font-size: 0.78rem;
+  color: var(--md-default-fg-color--light);
+  line-height: 1.5;
+}
+
+/* ============================================================
+   Features section
+   ============================================================ */
+
+.mdx-features {
+  padding: 4rem 0;
+}
+
+.mdx-features__grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 1.5rem;
+  margin-bottom: 2rem;
+}
+
+@media screen and (max-width: 76.25em) {
+  .mdx-features__grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media screen and (max-width: 44.9375em) {
+  .mdx-features__grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.mdx-feature-card {
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 0.5rem;
+  padding: 1.5rem;
+  transition: border-color 0.2s, box-shadow 0.2s;
+}
+
+.mdx-feature-card:hover {
+  border-color: var(--md-accent-fg-color);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+}
+
+.mdx-feature-card__icon {
+  font-size: 2rem;
+  margin-bottom: 0.75rem;
+}
+
+.mdx-feature-card h3 {
+  font-size: 1rem;
+  font-weight: 600;
+  margin: 0 0 0.5rem;
+}
+
+.mdx-feature-card p {
+  font-size: 0.875rem;
+  line-height: 1.65;
+  color: var(--md-default-fg-color--light);
+  margin: 0;
+}

package/docs/svelte.md

@@ -0,0 +1,71 @@
+---
+id: svelte
+title: Create a Full-Stack app with Svelte and ChadStart
+description: Quick start guide to create a full-stack app using Svelte as a frontend and ChadStart as a backend.
+---
+
+# Quick start with Svelte
+
+Give a proper backend to your Svelte app.
+
+!!! warning
+    This quick start guide focuses exclusively on the **frontend**. To ensure the functionality of this code, your ChadStart backend must be [up and running](./getting-started.md#install-chadstart) at `http://localhost:3000`.
+
+## 1. Create a Svelte app
+
+If you already have a Svelte app running, you can skip this step.
+
+There are several ways to do that. In our example we use [SvelteKit](https://kit.svelte.dev/) to generate a pre-configured Svelte app, you . You can replace `my-client` by the name of your front-end app.
+
+```
+npm create svelte@latest my-client
+cd my-client
+npm install
+npm run dev -- --open
+```
+
+## 2. Install ChadStart SDK
+
+Install the JS SDK from the root of your Svelte app.
+
+```
+npm i @chadstart/sdk
+```
+
+## 3. Use it in your app
+
+In that example we are using a Cat entity [created previously](entities.md). Replace it by your own entity. This example uses TypeScript, you can remove the typing to have plain JS.
+
+```js title="src/routes/+page.svelte"
+
+
+<script lang="ts">
+  import ChadStart from "@chadstart/sdk";
+  import { onMount } from "svelte";
+
+  interface Cat {
+    id: string;
+    name: string;
+    type: string;
+    image: string;
+  }
+
+  let cats: Cat[] = [];
+
+  onMount(async () => {
+    const chadstart = new ChadStart();
+    const result = await chadstart.from("cats").find<Cat>();
+    cats = result.data;
+  });
+</script>
+
+<div class="main">
+  <ul>
+    {#each cats as cat}
+      <li>{cat.name}</li>
+    {/each}
+  </ul>
+</div>
+```
+
+Checkout the [SDK doc](./crud.md#using-the-javascript-sdk) to see more usages of the SDK: CRUD operations, file upload, authentication,

package/docs/telemetry.md

@@ -0,0 +1,97 @@
+---
+id: telemetry
+title: Telemetry
+description: Monitor your ChadStart backend with OpenTelemetry. Send traces and metrics to any OTLP-compatible backend like Grafana, Datadog, or Jaeger.
+---
+
+# Telemetry
+
+ChadStart includes built-in observability via **OpenTelemetry** (OTel). Enable it to export distributed traces to any OTLP-compatible collector such as [Grafana Tempo](https://grafana.com/oss/tempo/), [Datadog](https://www.datadoghq.com/), [Jaeger](https://www.jaegertracing.io/), or [Honeycomb](https://www.honeycomb.io/).
+
+## Configuration
+
+Add a `telemetry` block to your `chadstart.yaml`:
+
+```yaml title="chadstart.yaml"
+telemetry:
+  enabled: true
+  serviceName: my-app
+  endpoint: http://localhost:4318
+```
+
+| Option          | Default                    | Description                                               |
+| --------------- | -------------------------- | --------------------------------------------------------- |
+| **enabled**     | `false`                    | Set to `true` to activate OpenTelemetry tracing           |
+| **serviceName** | `chadstart-app`            | The service name reported to your collector               |
+| **endpoint**    | `http://localhost:4318`    | Base URL of your OTLP collector (HTTP protocol)           |
+
+!!! warning "Auth headers are secrets"
+    If your collector requires an API key or bearer token, **never** put it in `chadstart.yaml`. Use the `OTEL_EXPORTER_OTLP_HEADERS` environment variable instead (see below).
+
+## Environment variables
+
+All telemetry options can be set (or overridden) via environment variables. Environment variables always take precedence over YAML values.
+
+| Variable                        | Description                                                                              |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `OTEL_ENABLED=true`             | Enable tracing (overrides `telemetry.enabled`)                                           |
+| `OTEL_SERVICE_NAME`             | Service name sent to the collector (overrides `telemetry.serviceName`)                   |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`   | Collector base URL (overrides `telemetry.endpoint`)                                      |
+| `OTEL_EXPORTER_OTLP_HEADERS`    | Comma-separated `key=value` auth headers, e.g. `authorization=Bearer <token>` **(secrets — env only)** |
+
+Add these to your `.env` file:
+
+```bash title=".env"
+OTEL_ENABLED=true
+OTEL_SERVICE_NAME=my-app
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.example.com
+OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer my-secret-token
+```
+
+## Example: Grafana Cloud
+
+1. Create a free account at [grafana.com](https://grafana.com/auth/sign-up).
+2. Go to **My Account → Grafana Cloud → OpenTelemetry**.
+3. Copy your OTLP endpoint and instance token.
+4. Add the following to your `.env`:
+
+```bash title=".env"
+OTEL_ENABLED=true
+OTEL_SERVICE_NAME=my-app
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-eu-west-0.grafana.net/otlp
+OTEL_EXPORTER_OTLP_HEADERS=authorization=Basic <base64-encoded-token>
+```
+
+## Example: Datadog
+
+```bash title=".env"
+OTEL_ENABLED=true
+OTEL_SERVICE_NAME=my-app
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.datadoghq.com
+OTEL_EXPORTER_OTLP_HEADERS=DD-API-KEY=<your-datadog-api-key>
+```
+
+## Local development with Jaeger
+
+Run a local [Jaeger](https://www.jaegertracing.io/) instance with Docker to visualise traces during development:
+
+```bash
+docker run -d --name jaeger \
+  -p 16686:16686 \
+  -p 4318:4318 \
+  jaegertracing/all-in-one:latest
+```
+
+Then in your `chadstart.yaml`:
+
+```yaml title="chadstart.yaml"
+telemetry:
+  enabled: true
+  serviceName: my-app
+  endpoint: http://localhost:4318
+```
+
+Open [http://localhost:16686](http://localhost:16686) to explore traces.
+
+!!! note
+    Telemetry uses the OTLP **HTTP** protocol on port `4318` (not the gRPC port `4317`). Make sure your collector is configured to accept HTTP.

package/docs/upload.md

@@ -0,0 +1,168 @@
+---
+id: upload
+title: File and Image Uploads
+description: Upload files and images with ChadStart built-in storage system to upload assets in the file storage or any S3-compatible storage.
+---
+
+# Uploads
+
+## Introduction
+
+ChadStart comes with a **built-in storage system** to upload assets locally (default) or in a [S3 bucket](./s3-storage.md). You can use [file upload](#upload-a-file) to let your users update any kind of file, or [image upload](#upload-an-image) for image resizing.
+
+A `public/storage` folder is automatically created when needed. Uploaded files and images will be renamed with a unique name and stored in a specific folder based on entity and property name, ending by a folder with the current month name to prevent having too many files in a single folder.
+
+Example: _public/storage/project/contract/Nov24/8dab3936m1p54a66-contract.pdf_
+
+!!! warning
+    If you want to set this file as an item's property, you need to upload the file first and then add the new uploaded file path as the property value creating or updating a record.
+
+## Add a BASE_URL variable
+
+ChadStart stores absolute paths for convenience.
+
+By default the base url is set to `http://localhost:${port}` but you can change it using the `BASE_URL` environment variable in your `.env` file to adapt to your own base URL.
+
+Example: `BASE_URL=https://example.com`.
+
+!!! warning
+    Changing the `BASE_URL` will not change the path of images and files that are already stored but it will impact the new ones.
+
+## Upload a file
+
+A file should be related to a property with the [file property type](./entities.md#file).
+
+=== "JS SDK"
+    ```js
+
+    // Create a Blob, adapt this step to your use case.
+    const file = new Blob(['Hello, this is a test file!'], {
+      type: 'text/plain',
+    })
+
+    // Upload a file that will be used as a contract for an invoice.
+    const file = await chadstart.from('invoices').upload('contract', file)
+
+    console.log(file)
+    // Output: {"path":"http://localhost:3000/invoices/contract/Oct2024/8dabo9qm1q3swvu-my-contract.pdf"}
+
+    // Then you can store the path in the database.
+    const invoice = await chadstart.from('invoices').create({
+      name: 'Invoice ACME',
+      contract: file.path
+    })
+    ```
+
+=== "REST API"
+    ```http
+    // Upload file.
+    POST /api/upload/file
+    Content-Type: multipart/form-data
+    {
+        file: (binary)
+        entity: invoices
+        property: contract
+    }
+
+    // Response.
+    {
+        "path":"http://localhost:3000/invoices/contract/Oct2024/8dabo9qm1q3swvu-my-contract.pdf"
+    }
+    ```
+
+## Upload an image
+
+An image should be related to a property with the [image property type](./entities.md#image). ChadStart accepts **.PNG** and **.JPG** images only.
+
+### Default behavior
+
+By default, uploaded images are **compressed to JPEG** at quality 80. Resizing is **not applied** unless sizes are explicitly configured in the YAML — the image is stored as-is (after compression).
+
+### Disable compression
+
+Set `compress: false` on the image property to keep the original file untouched:
+
+```yaml
+entities:
+  Cat:
+    properties:
+      - name: avatar
+        type: image
+        options:
+          compress: false
+```
+
+You can also adjust the JPEG quality (1–100, default `80`):
+
+```yaml
+options:
+  quality: 60
+```
+
+### Enable resizing
+
+Define `sizes` on the image property to resize the image into one or more named variants. Each variant is stored as a separate JPEG file and the response contains a URL for each:
+
+```yaml
+entities:
+  Cat:
+    properties:
+      - name: avatar
+        type: image
+        options:
+          sizes:
+            thumbnail: [80, 80]
+            medium: [160, 160]
+```
+
+When sizes are configured, compression also applies to each resized variant (set `compress: false` to use lossless quality instead).
+
+=== "JS SDK"
+    ```js
+    // Create a Blob from an image, adapt this step to your use case.
+    const base64Image =
+      'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/wcAAwAB/eb7jLwAAAAASUVORK5CYII='
+    const imageBlob: Blob = base64ToBlob(base64Image, 'image/png')
+
+    // Upload the image (default: compressed to JPEG, no resize).
+    const image = await chadstart.from('cats').uploadImage('avatar', imageBlob)
+
+    console.log(image)
+    // Output (no sizes configured):
+    // { "path": "http://localhost:3000/cats/avatar/Oct2024/8dabo9qm1q4n1nk-avatar.jpg" }
+
+    // Output (sizes configured in YAML):
+    // {
+    //   "medium": "http://localhost:3000/cats/avatar/Oct2024/8dabo9qm1q4n1nk-medium.jpg",
+    //   "thumbnail": "http://localhost:3000/cats/avatar/Oct2024/8dabo9qm1q4n1nk-thumbnail.jpg"
+    // }
+
+    // Then you can store the path in the database.
+    const cat = await chadstart.from('cats').create({
+      name: 'Felix',
+      image: image
+    })
+    ```
+
+=== "REST API"
+    ```http
+    // Upload image.
+    POST /api/upload/image
+    Content-Type: multipart/form-data
+    {
+        image: (binary)
+        entity: cats
+        property: avatar
+    }
+
+    // Response (no sizes configured — default):
+    {
+      "path": "http://localhost:3000/cats/avatar/Oct2024/8dabo9qm1q4n1nk-avatar.jpg"
+    }
+
+    // Response (sizes configured in YAML):
+    {
+      "medium": "http://localhost:3000/cats/avatar/Oct2024/8dabo9qm1q4n1nk-medium.jpg",
+      "thumbnail": "http://localhost:3000/cats/avatar/Oct2024/8dabo9qm1q4n1nk-thumbnail.jpg"
+    }
+    ```