Update documentation content

2026-03-15 05:32:05 +01:00
parent 7d10f030f3
commit c0b92596ec
30 changed files with 1840 additions and 29 deletions
@@ -0,0 +1,93 @@
+---
+title: API CRUD DELETE | Datasquirel docs
+description: Delete a record from a Datasquirel table via the API
+page_title: DELETE
+page_description: Delete one or more records from a table using the Datasquirel REST API or npm package.
+---
+
+## Overview
+
+Use the DELETE endpoint to remove records from a table. You can delete by a specific record ID or by matching field values.
+
+## npm Package
+
+### Delete by ID
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.crud.delete({
+    dbName: "my_database",
+    tableName: "users",
+    targetID: 42,
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+### Delete by Field Value
+
+```javascript
+const result = await datasquirel.crud.delete({
+    dbName: "my_database",
+    tableName: "sessions",
+    deleteSpec: {
+        deleteKeyValues: [
+            { key: "user_id", value: 42, operator: "=" },
+        ],
+    },
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dbName` | `string` | Yes | The database slug |
+| `tableName` | `string` | Yes | The table to delete from |
+| `targetID` | `string \| number` | No | The `id` of the record to delete. Either `targetID` or `deleteSpec` is required |
+| `deleteSpec` | `object` | No | Field-value conditions for deletion (see below) |
+| `apiKey` | `string` | No | API key. Falls back to `DATASQUIREL_API_KEY` environment variable |
+
+### deleteSpec.deleteKeyValues
+
+An array of conditions. Each condition has:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | The field name to match |
+| `value` | `string \| number \| null` | The value to match against |
+| `operator` | `string` | Comparison operator — `"="`, `"!="`, `">"`, `"<"`, etc. Defaults to `"="` |
+
+## REST API
+
+```
+DELETE /api/v1/crud/{dbName}/{tableName}/{id}
+DELETE /api/v1/crud/{dbName}/{tableName}
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+```
+
+**Body (when deleting by field value):**
+```json
+{
+    "deleteKeyValues": [
+        { "key": "user_id", "value": 42, "operator": "=" }
+    ]
+}
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": 1
+}
+```
+
+A successful response returns `success: true` and `payload` with the number of deleted rows.
@@ -0,0 +1,104 @@
+---
+title: API CRUD GET | Datasquirel docs
+description: Fetch records from a Datasquirel table via the API
+page_title: GET
+page_description: Read one or more records from a table using the Datasquirel REST API or npm package.
+---
+
+## Overview
+
+Use the GET endpoint to fetch records from any table in your database. You can retrieve all records, a single record by ID, or a filtered and paginated subset.
+
+## npm Package
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.crud.get({
+    dbName: "my_database",
+    tableName: "users",
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+
+// result.payload contains the array of records
+console.log(result.payload);
+```
+
+### Get a Single Record by ID
+
+```javascript
+const result = await datasquirel.crud.get({
+    dbName: "my_database",
+    tableName: "users",
+    targetId: 42,
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+### Filtered and Paginated Query
+
+```javascript
+const result = await datasquirel.crud.get({
+    dbName: "my_database",
+    tableName: "posts",
+    apiKey: process.env.DATASQUIREL_API_KEY,
+    query: {
+        limit: 10,
+        page: 1,
+        order: { field: "created_at", strategy: "DESC" },
+        query: {
+            is_published: { value: 1, equality: "=" },
+        },
+    },
+});
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dbName` | `string` | Yes | The database slug to query |
+| `tableName` | `string` | Yes | The table to read from |
+| `apiKey` | `string` | No | API key. Falls back to the `DATASQUIREL_API_KEY` environment variable |
+| `targetId` | `string \| number` | No | Fetch a single record by its `id` |
+| `query` | `object` | No | Filter, pagination, and ordering options (see below) |
+
+### Query Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `limit` | `number` | Maximum number of records to return |
+| `page` | `number` | Page number for pagination (1-based) |
+| `offset` | `number` | Number of records to skip |
+| `order` | `{ field, strategy }` | Sort by a field — `strategy` is `"ASC"` or `"DESC"` |
+| `selectFields` | `string[]` | Only return these fields |
+| `omitFields` | `string[]` | Exclude these fields from the result |
+| `query` | `object` | Field-level filters — each key is a field name with a `value` and `equality` |
+| `fullTextSearch` | `object` | Full-text search across specified fields |
+| `join` | `array` | JOIN conditions against other tables |
+
+## REST API
+
+```
+GET /api/v1/crud/{dbName}/{tableName}
+GET /api/v1/crud/{dbName}/{tableName}/{id}
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": [
+        { "id": 1, "name": "Alice", "email": "[email protected]" },
+        { "id": 2, "name": "Bob", "email": "[email protected]" }
+    ]
+}
+```
+
+A successful response has `success: true` and a `payload` array. A single-record fetch (by `targetId`) returns `payload` as an object.
@@ -0,0 +1,46 @@
+---
+title: API CRUD OPTIONS | Datasquirel docs
+description: Inspect available CRUD operations for a table
+page_title: OPTIONS
+page_description: Retrieve metadata about the CRUD operations available for a table.
+---
+
+## Overview
+
+The OPTIONS endpoint returns metadata about the available operations for a given table — useful for dynamically discovering what fields and actions are supported.
+
+## REST API
+
+```
+OPTIONS /api/v1/crud/{dbName}/{tableName}
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+## Response
+
+The response includes information about the table schema and the HTTP methods supported for that table.
+
+```json
+{
+    "success": true,
+    "payload": {
+        "methods": ["GET", "POST", "PUT", "DELETE"],
+        "schema": [
+            { "name": "id", "type": "int", "required": true },
+            { "name": "name", "type": "varchar(255)", "required": true },
+            { "name": "email", "type": "varchar(255)", "required": false }
+        ]
+    }
+}
+```
+
+## Related
+
+- [GET](/docs/api-reference/crud/get) — read records
+- [POST](/docs/api-reference/crud/post) — create records
+- [PUT](/docs/api-reference/crud/put) — update records
+- [DELETE](/docs/api-reference/crud/delete) — delete records
@@ -0,0 +1,88 @@
+---
+title: API CRUD POST | Datasquirel docs
+description: Create a new record in a Datasquirel table via the API
+page_title: POST
+page_description: Insert a new record into a table using the Datasquirel REST API or npm package.
+---
+
+## Overview
+
+Use the POST endpoint to insert a new record into a table. Provide the data as a plain object — the keys must match your table's field names.
+
+## npm Package
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.crud.insert({
+    dbName: "my_database",
+    tableName: "users",
+    body: {
+        name: "Alice",
+        email: "[email protected]",
+        is_active: 1,
+    },
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+
+// result.payload is the inserted record's ID
+console.log(result.payload);
+```
+
+### Insert Multiple Records (Batch)
+
+You can insert multiple records in a single request by passing an array in a `batchData` field:
+
+```javascript
+const result = await datasquirel.crud.insert({
+    dbName: "my_database",
+    tableName: "tags",
+    body: { batchData: [
+        { name: "javascript" },
+        { name: "typescript" },
+        { name: "sql" },
+    ]},
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dbName` | `string` | Yes | The database slug |
+| `tableName` | `string` | Yes | The table to insert into |
+| `body` | `object` | Yes | The record to insert. Keys must match field names |
+| `apiKey` | `string` | No | API key. Falls back to `DATASQUIREL_API_KEY` environment variable |
+
+## REST API
+
+```
+POST /api/v1/crud/{dbName}/{tableName}
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+    "name": "Alice",
+    "email": "[email protected]",
+    "is_active": 1
+}
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": 7
+}
+```
+
+A successful response returns `success: true` and `payload` containing the `insertId` (the auto-incremented `id` of the new record).
@@ -0,0 +1,68 @@
+---
+title: API CRUD PUT | Datasquirel docs
+description: Update an existing record in a Datasquirel table via the API
+page_title: PUT
+page_description: Update an existing record in a table using the Datasquirel REST API or npm package.
+---
+
+## Overview
+
+Use the PUT endpoint to update an existing record. You must provide the `id` of the record you want to update, along with the fields you want to change. Only the fields you include in the body are updated — other fields are left unchanged.
+
+## npm Package
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.crud.update({
+    dbName: "my_database",
+    tableName: "users",
+    targetID: 42,
+    body: {
+        name: "Alice Updated",
+        is_active: 0,
+    },
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dbName` | `string` | Yes | The database slug |
+| `tableName` | `string` | Yes | The table to update |
+| `targetID` | `string \| number` | Yes | The `id` of the record to update |
+| `body` | `object` | Yes | Fields to update. Keys must match field names |
+| `apiKey` | `string` | No | API key. Falls back to `DATASQUIREL_API_KEY` environment variable |
+
+## REST API
+
+```
+PUT /api/v1/crud/{dbName}/{tableName}/{id}
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+    "name": "Alice Updated",
+    "is_active": 0
+}
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": 1
+}
+```
+
+A successful response returns `success: true` and `payload` with the number of affected rows (typically `1`).
@@ -0,0 +1,56 @@
+---
+title: API Media DELETE | Datasquirel docs
+description: Delete a media file via the Datasquirel API
+page_title: Media DELETE
+page_description: Delete a media file from your Datasquirel media storage using the API.
+---
+
+## Overview
+
+Use the Media DELETE endpoint to permanently remove a file from your media storage. Provide the file's database ID to identify which file to delete.
+
+## npm Package
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.media.delete({
+    mediaID: 23,
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+
+console.log(result.success); // true
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mediaID` | `string \| number` | Yes | The database ID of the file to delete |
+| `apiKey` | `string` | No | API key. Falls back to `DATASQUIREL_API_KEY` |
+
+## REST API
+
+```
+DELETE /api/v1/media/{id}
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": { "id": 23 }
+}
+```
+
+## Notes
+
+- A **Full Access** API key is required. Read-only keys cannot delete files.
+- Deletion is permanent. The file and its thumbnail are both removed from storage.
+- Use the [Media GET](/docs/api-reference/media/get) endpoint to look up a file's ID before deleting.
@@ -0,0 +1,91 @@
+---
+title: API Media GET | Datasquirel docs
+description: Retrieve media file metadata via the Datasquirel API
+page_title: Media GET
+page_description: Retrieve a media file or a list of media files using the Datasquirel API.
+---
+
+## Overview
+
+Use the Media GET endpoint to retrieve metadata for one or more media files. You can look up a file by its database ID, by name, or list all files in a folder.
+
+## npm Package
+
+### Get All Media Files
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.media.get({
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+
+console.log(result.payload); // Array of media objects
+```
+
+### Get a Single File by ID
+
+```javascript
+const result = await datasquirel.media.get({
+    mediaID: 15,
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+### Get Files in a Specific Folder
+
+```javascript
+const result = await datasquirel.media.get({
+    folder: "profile-images",
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+### Get a File by Name
+
+```javascript
+const result = await datasquirel.media.get({
+    mediaName: "avatar.jpg",
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mediaID` | `string \| number` | No | The database ID of the media file |
+| `mediaName` | `string` | No | The file name to look up |
+| `folder` | `string` | No | Folder name to filter results |
+| `thumbnail` | `"true" \| "false"` | No | Return thumbnail URL instead of original |
+| `skipBase64` | `"true" \| "false"` | No | Skip base64 encoding in the response |
+| `apiKey` | `string` | No | API key. Falls back to `DATASQUIREL_API_KEY` |
+
+## REST API
+
+```
+GET /api/v1/media
+GET /api/v1/media/{id}
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": {
+        "id": 15,
+        "name": "avatar.jpg",
+        "folder": "profile-images",
+        "url": "https://your-instance.com/media/profile-images/avatar.jpg",
+        "thumbnail_url": "https://your-instance.com/media/profile-images/thumbs/avatar.jpg",
+        "size": 24576,
+        "mime_type": "image/jpeg"
+    }
+}
+```
@@ -0,0 +1,44 @@
+---
+title: API Media Reference | Datasquirel docs
+description: Manage media files via the Datasquirel API
+page_title: Media API
+page_description: Upload, retrieve, and delete media files programmatically using the Datasquirel API.
+---
+
+## Overview
+
+The Media API lets you manage files stored in your Datasquirel media storage. Use it to upload files from your application, retrieve file metadata, and delete files that are no longer needed.
+
+```bash
+npm install @moduletrace/datasquirel
+```
+
+<div className="w-full grid grid-cols-1 gap-4 items-stretch">
+    <DocsCard
+        title="GET"
+        description="Retrieve media file metadata or a list of files."
+        href="/docs/api-reference/media/get"
+    />
+    <DocsCard
+        title="POST"
+        description="Upload a new media file."
+        href="/docs/api-reference/media/post"
+    />
+    <DocsCard
+        title="DELETE"
+        description="Delete a media file."
+        href="/docs/api-reference/media/delete"
+    />
+</div>
+
+## Authentication
+
+All media API requests require a **Full Access** API key. Read-only keys cannot upload or delete media.
+
+Include your key in the `Authorization` header:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+Or pass it as `apiKey` in the npm package function call.
@@ -0,0 +1,99 @@
+---
+title: API Media POST | Datasquirel docs
+description: Upload a media file via the Datasquirel API
+page_title: Media POST
+page_description: Upload images and files to your Datasquirel media storage programmatically.
+---
+
+## Overview
+
+Use the Media POST endpoint to upload one or more files to your media storage. Files are stored in the folder you specify, and image thumbnails are generated automatically.
+
+## npm Package
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+import fs from "fs";
+
+// Read the file and convert to base64
+const fileBuffer = fs.readFileSync("./photo.jpg");
+const base64 = fileBuffer.toString("base64");
+
+const result = await datasquirel.media.add({
+    media: [
+        {
+            name: "photo.jpg",
+            base64: `data:image/jpeg;base64,${base64}`,
+        },
+    ],
+    folder: "profile-images",
+    type: "image",
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+
+console.log(result.payload); // Uploaded media object(s)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `media` | `array` | Yes | Array of files to upload. Each item has a `name` and `base64` string |
+| `folder` | `string` | No | Destination folder name. Created automatically if it does not exist |
+| `type` | `string` | Yes | File type — `"image"`, `"video"`, `"audio"`, or `"file"` |
+| `apiKey` | `string` | No | API key. Falls back to `DATASQUIREL_API_KEY` |
+
+### media Array Items
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | The file name including extension (e.g. `"photo.jpg"`) |
+| `base64` | `string` | Base64-encoded file data. Must include the data URL prefix (e.g. `data:image/jpeg;base64,...`) |
+
+## REST API
+
+```
+POST /api/v1/media
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+    "media": [
+        {
+            "name": "photo.jpg",
+            "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
+        }
+    ],
+    "folder": "profile-images",
+    "type": "image"
+}
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": [
+        {
+            "id": 23,
+            "name": "photo.jpg",
+            "folder": "profile-images",
+            "url": "https://your-instance.com/media/profile-images/photo.jpg"
+        }
+    ]
+}
+```
+
+## Notes
+
+- A **Full Access** API key is required. Read-only keys cannot upload files.
+- Image thumbnails are generated automatically and stored alongside the original.
+- Uploading a file with the same name as an existing file in the same folder will overwrite it if `update: true` is passed.
@@ -0,0 +1,37 @@
+---
+title: API SQL Reference | Datasquirel docs
+description: Execute raw SQL queries via the Datasquirel API
+page_title: SQL API
+page_description: Run raw MariaDB SQL queries against your databases using the Datasquirel API.
+---
+
+## Overview
+
+The SQL API lets you execute any valid MariaDB SQL statement directly against your database and receive the result set as JSON. Use it when the standard CRUD endpoints don't cover your use case — complex JOINs, aggregations, subqueries, or DDL operations.
+
+<div className="w-full grid grid-cols-1 gap-4 items-stretch">
+    <DocsCard
+        title="OPTIONS"
+        description="Execute a raw SQL query against your database."
+        href="/docs/api-reference/sql/options"
+    />
+</div>
+
+## Quick Example
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.api.sql({
+    key: process.env.DATASQUIREL_API_KEY,
+    params: {
+        query: "SELECT * FROM users WHERE is_active = 1 ORDER BY created_at DESC LIMIT 10",
+    },
+});
+
+console.log(result.payload);
+```
+
+## Authentication
+
+A **Full Access** API key is required to run raw SQL queries. Read-only keys cannot use the SQL endpoint.
@@ -0,0 +1,81 @@
+---
+title: API SQL OPTIONS | Datasquirel docs
+description: Execute a raw SQL query via the Datasquirel API
+page_title: SQL OPTIONS
+page_description: Execute any valid MariaDB SQL statement and receive results as JSON.
+---
+
+## Overview
+
+The SQL OPTIONS endpoint accepts any valid MariaDB SQL string and executes it against your database. Results are returned as a JSON array.
+
+## npm Package
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+
+const result = await datasquirel.api.sql({
+    key: process.env.DATASQUIREL_API_KEY,
+    params: {
+        query: "SELECT posts.id, posts.title, users.name AS author FROM posts JOIN users ON posts.user_id = users.id WHERE posts.is_published = 1 ORDER BY posts.created_at DESC LIMIT 20",
+    },
+});
+
+console.log(result.payload);
+```
+
+### Aggregation Query
+
+```javascript
+const result = await datasquirel.api.sql({
+    key: process.env.DATASQUIREL_API_KEY,
+    params: {
+        query: "SELECT category, COUNT(*) AS total FROM posts GROUP BY category ORDER BY total DESC",
+    },
+});
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `key` | `string` | Yes | Full Access API key |
+| `params.query` | `string` | Yes | The raw MariaDB SQL string to execute |
+
+## REST API
+
+```
+POST /api/v1/sql
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+    "query": "SELECT * FROM users WHERE is_active = 1 LIMIT 10"
+}
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": [
+        { "id": 1, "name": "Alice", "email": "[email protected]" },
+        { "id": 2, "name": "Bob", "email": "[email protected]" }
+    ]
+}
+```
+
+## Notes
+
+- A **Full Access** API key is required.
+- All valid MariaDB statements are supported: SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP, and more.
+- Be careful with DDL statements (ALTER, DROP) — they modify the table structure and cannot be undone.
+- Parameterized queries are not supported through this endpoint — sanitize user input before embedding it in a SQL string.