laravel-request 1.2.26 → 1.2.27

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "laravel-request",
   "productName": "laravel-request",
-  "version": "1.2.26",
+  "version": "1.2.27",
   "description": "laravel-request",
   "main": "src/index.js",
   "module": "src/index.js",

package/readme.md

@@ -1,111 +1,266 @@
-Install
+# laravel-request
 
+Клиентская библиотека для работы с Laravel API. Поддерживает JSON и MessagePack, fluent-интерфейс в стиле Eloquent Query Builder.
+
+## Содержание
+
+- [Установка](#установка)
+- [Переменные окружения](#переменные-окружения)
+- [Api](#api)
+- [ApiRequest](#apirequest)
+  - [Два типа запросов](#два-типа-запросов)
+  - [Выборки: примеры и payload](#выборки-примеры-и-payload)
+  - [Действия: call()](#действия-call)
+  - [Отключение уведомлений](#отключение-уведомлений)
+  - [Прямой вызов по URL](#прямой-вызов-по-url)
+  - [Отмена запроса](#отмена-запроса)
+- [Лицензия](#лицензия)
+
+---
+
+## Установка
+
+```bash
 npm install laravel-request
+```
+
+## Переменные окружения
+
+| Переменная | Описание |
+|------------|----------|
+| `REACT_APP_API_URL` | Базовый URL API |
+| `REACT_APP_DEBUG` | `true`/`false` — логирование запросов и ответов |
+
+---
+
+## Api
+
+```javascript
+import { Api } from 'laravel-request';
+```
+
+| Метод | Описание |
+|-------|----------|
+| `Api.get(controller, action, data)` | GET |
+| `Api.post(controller, action, data)` | POST |
+| `Api.put(controller, action, data)` | PUT |
+| `Api.patch(controller, action, data)` | PATCH |
+| `Api.delete(controller, action, id, data)` | DELETE |
+| `Api.getArg(controller, action, arg, data)` | GET с аргументом в URL (например, index/123) |
+| `Api.getUrl(url, data)` | Прямой GET по URL |
 
-Connected package
+URL формируется как: `{domain}/api/v1/call/{controller}/{action}`
 
-https://github.com/olegstan/laravel-rest
+---
 
-set domain resolver before any request
+## ApiRequest
 
+### Два типа запросов
+
+**Выборка (список)** — `Api.get(controller, 'index')` или `'list'`  
+Цепочка `where()`, `select()`, `orderBy()` и т.д. + метод выполнения:
+
+| Метод | Результат |
+|-------|-----------|
+| `first()` | Первая страница |
+| `all()` | Все записи |
+| `paginate(page, perPage)` | Страница с пагинацией |
+| `pluck(fields)` | Только указанные поля |
+| `call()` | Без указания способа |
+
+**Действие** — POST/PUT/PATCH/DELETE или GET одной записи (index)  
+Всегда завершается `call()`.
+
+### Выборки: примеры и payload
+
+Данные уходят в query-параметрах URL (или в теле POST, если длина >5000 символов).
+
+При `REACT_APP_API_URL=https://api.example.com` URL формируется как `https://api.example.com/api/v1/call/{controller}/{action}`.
+
+**first():**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .select(['id', 'name', 'price'])
+  .where('status', '=', 'active')
+  .orderBy('created_at', 'desc')
+  .first(success, error, final);
 ```
-Api.domainResolver = () => {
-    try {
-        return Environment.get('REACT_APP_API_URL');
-    } catch (e) {
-        console.log(e)
-        return null;
-    }
+```json
+{
+  "arguments": [],
+  "query": [
+    { "select": [["id", "name", "price"]] },
+    { "where": ["status", "=", "active"] },
+    { "orderBy": ["created_at", "desc"] }
+  ],
+  "data": { "paginateType": "first" },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
 }
 ```
 
-set auth token resolver before any request
+**all():**
 
-default token resolver, you can redefine it to any other
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .where('category_id', '=', 1)
+  .all(success, error, final);
 ```
-Api.tokenResolver = async () => {
-    try {
-        return await localStorage.getItem('api_token'); 
-    } catch (e) {
-        console.log(e)
-        return null;
-    }
+```json
+{
+  "arguments": [],
+  "query": [{ "where": ["category_id", "=", 1] }],
+  "data": { "paginateType": "all" },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
 }
 ```
 
-Usage get data
+**paginate():**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
 
+```javascript
+Api.get('product', 'index')
+  .whereIn('category_id', [1, 2, 3])
+  .orderBy('name')
+  .paginate(2, 15, success, error, final);
 ```
-Api.get('active-trade', 'index')
-      .where('active_id', 115)
-      .with('currency')
-      .with('to_account', 'to_account.currency')
-      .with('from_account', 'from_account.currency')
-      .orderBy('trade_at', 'DESC')
-      .all((response) => {
-        //success
-      }, () => {
-        //error
-      })
-}}     
+```json
+{
+  "arguments": [],
+  "query": [
+    { "whereIn": ["category_id", [1, 2, 3]] },
+    { "orderBy": ["name"] }
+  ],
+  "data": {
+    "paginateType": "paginate",
+    "page": 2,
+    "perPage": 15
+  },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
 ```
-  
-or
 
+**pluck():**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .pluck(['id', 'name'], success, error, final);
 ```
-Api.get('active-trade', 'index')
-      .where('id', 115)
-      .with('currency')
-      .with('to_account', 'to_account.currency')
-      .with('from_account', 'from_account.currency')
-      .orderBy('trade_at', 'DESC')
-      .first((response) => {
-        //success
-        
-      }, () => {
-        //error
-      })
-}}
+```json
+{
+  "arguments": [],
+  "query": [],
+  "data": {
+    "paginateType": "pluck",
+    "fields": ["id", "name"]
+  },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
 ```
 
-  
-You can use
-
-all or first or paginate
+**first() — сложный (whereHas, with):**
 
-usage POST data
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
 
+```javascript
+Api.get('product', 'index')
+  .select(['id', 'name', 'price'])
+  .where('status', '=', 'active')
+  .whereHas('category', (q) => q.where('visible', true))
+  .with(['images', 'category'])
+  .orderBy('created_at', 'desc')
+  .first(success, error, final);
 ```
-Api.post('active', 'store', {
-      user_id: this.props.client.id,
-      type: 2,
-      type_id: item.type_id
-    })
-      .call((response) => {
-        //success
-      }, (response) => {
-        //error
-      });
+```json
+{
+  "arguments": [],
+  "query": [
+    { "select": [["id", "name", "price"]] },
+    { "where": ["status", "=", "active"] },
+    { "whereHas": ["category", { "query": [{ "where": ["visible", true] }] }] },
+    { "with": [["images", "category"]] },
+    { "orderBy": ["created_at", "desc"] }
+  ],
+  "data": { "paginateType": "first" },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
 ```
 
-response must be like below, for 200 status should contains key "result" with text "success"
+**getArg()** (например, index/123):
+
+URL: `https://api.example.com/api/v1/call/user/index` (GET, id=123 в payload)
 
+```javascript
+Api.getArg('user', 'index', 123).call(success, error, final);
+```
+```json
 {
-    "meta": [],
-    "result": "success",
-    "data": [],
+  "arguments": [123],
+  "query": [],
+  "data": {},
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
 }
+```
+
+### Действия: call()
 
-you can cancel request by
+```javascript
+// URL: https://api.example.com/api/v1/call/user/store (POST)
+Api.post('user', 'store', { name: 'John', email: 'john@example.com' })
+  .call(success, error, final);
 
+// URL: https://api.example.com/api/v1/call/user/update (PUT)
+Api.put('user', 'update', { id: 1, name: 'John' })
+  .call(success, error, final);
+
+// URL: https://api.example.com/api/v1/call/user/destroy (DELETE, id=123 в payload)
+Api.delete('user', 'destroy', 123)
+  .call(success, error, final);
+
+// URL: https://api.example.com/api/v1/call/user/index (GET, id=123 в payload)
+Api.getArg('user', 'index', 123)
+  .call(success, error, final);
 ```
 
-let cancelTokenSource = Api.get('active', SearchAllTypesHelper.ALL_TYPES, {
-            item_search: searchQuery,
-            user_id: clientId,
-            search_stock: 1
-        }).call(({data}) => {}, () => {}).getSource()
-        
-cancelTokenSource.cancel();
-        
+### Отключение уведомлений
+
+```javascript
+Api.get('product', 'index').withoutNotify().first(success, error, final);
+
+Api.post('user', 'store', data)
+  .withoutNotify((status) => status !== 422)
+  .call(success, error, final);
+```
+
+### Прямой вызов по URL
+
+```javascript
+Api.getUrl('https://api.example.com/custom/endpoint')
+  .callUrl(success, error, final);
 ```
+
+### Отмена запроса
+
+```javascript
+const request = Api.get('product', 'index').first(success, error, final);
+request.getSource().cancel();
+```
+
+---
+
+## Лицензия
+
+MIT © Abramov Oleg