Skip to content

Commit fb1a9aa

Browse files
author
Dheeraj TILHOO
committed
update documentation for sdk version 0.2.0
1 parent e3f0c83 commit fb1a9aa

File tree

11 files changed

+433
-0
lines changed

11 files changed

+433
-0
lines changed

‎.DS_Store‎

-8 KB
Binary file not shown.

‎content/1.getting-started/2.introduction.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,25 @@ Use this documentation to:
3434
2. Configure your HTTP client.
3535
3. Define models and repositories.
3636
4. Use search, mutate, delete, and actions in your Flutter app.
37+
38+
39+
## SDK Coverage & Recent Updates
40+
41+
The Flutter SDK provides a typed client for the Laravel Rest API (Lomkit),
42+
covering all main resource interactions:
43+
44+
- Search (filters, scopes, includes, aggregates, instructions, pagination)
45+
- Details (single resource retrieval with metadata and gates)
46+
- Mutate (create/update with nested relation operations)
47+
- Actions (custom resource actions)
48+
- Delete / Restore / Force Delete lifecycle
49+
- Gates & authorization metadata
50+
51+
### Recent improvements
52+
- Fixed nested mutate relation serialization
53+
- Correct pagination handling in search requests
54+
- Instruction payload alignment with backend expectations
55+
- Explicit null handling in filters and instruction fields
56+
- Full test coverage across all factories
57+
58+
For detailed examples, refer to the dedicated documentation sections.

‎content/2.sdk/1.overview.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: SDK Overview
3+
description: How the Flutter SDK maps to Laravel Rest API (Lomkit) endpoints and resources.
4+
---
5+
6+
# SDK Overview
7+
8+
This SDK is a thin, typed client for **Laravel Rest API (Lomkit)** resources.
9+
10+
You build a repository for a resource by mixing in the factories you need (Search, Details, Mutate, Actions, Delete…).
11+
Each factory knows how to build the request body and which endpoint to call.
12+
13+
## Covered features
14+
15+
- **Search**: filters, scopes, sorts, selects, includes, aggregates, instructions, pagination
16+
- **Details**: retrieve a single resource (optionally with includes / metadata)
17+
- **Mutate**: create/update + nested relation operations (attach/detach/sync/toggle…)
18+
- **Actions**: run server-side actions on resources
19+
- **Delete lifecycle**: delete, restore, force delete
20+
- **Gates**: parse authorization responses (boolean or `{ allowed, message }`)
21+
22+
> For full API concepts (Resources, scopes, instructions, gates), refer to the Lomkit docs.

‎content/2.sdk/2.quickstart.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: Quickstart
3+
description: Minimal setup and first calls (search, mutate, actions).
4+
---
5+
6+
# Quickstart
7+
8+
## 1) Configure Dio + SDK client
9+
10+
```dart
11+
import 'package:dio/dio.dart';
12+
import 'package:laravel_rest_api_flutter/laravel_rest_api_flutter.dart';
13+
14+
final dio = Dio(
15+
BaseOptions(
16+
baseUrl: 'https://api.example.com',
17+
headers: {
18+
'Accept': 'application/json',
19+
'Authorization': 'Bearer YOUR_TOKEN',
20+
},
21+
),
22+
);
23+
24+
final client = ApiHttpClient(dio: dio);
25+
```
26+
27+
## 2) Create a repository
28+
29+
```dart
30+
class ItemsRepository
31+
with
32+
SearchFactory<Map<String, dynamic>>,
33+
DeleteFactory<Map<String, dynamic>>,
34+
MutateFactory,
35+
ActionsFactory {
36+
final RestApiClient client;
37+
38+
ItemsRepository(this.client);
39+
40+
@override
41+
String get baseRoute => '/items';
42+
43+
@override
44+
RestApiClient get httpClient => client;
45+
46+
@override
47+
Map<String, dynamic> fromJson(Map<String, dynamic> json) => json;
48+
49+
@override
50+
void onCatchError(
51+
RestApiResponse? response,
52+
Object exception,
53+
StackTrace stacktrace,
54+
) {}
55+
}
56+
```
57+
58+
## 3) Call endpoints
59+
60+
### Search
61+
62+
```dart
63+
final repo = ItemsRepository(client);
64+
65+
final res = await repo.search(
66+
text: TextSearch(value: 'hammer'),
67+
page: 1,
68+
limit: 10,
69+
sorts: [Sort(field: 'created_at', direction: 'desc')],
70+
);
71+
72+
print(res.data); // List<Map<String, dynamic>>
73+
```
74+
75+
### Mutate
76+
77+
```dart
78+
final res = await repo.mutate(
79+
body: LaravelRestApiMutateBody(
80+
mutate: [
81+
Mutation(
82+
operation: MutationOperation.create,
83+
attributes: {'name': 'New item'},
84+
),
85+
],
86+
),
87+
);
88+
89+
print(res.data?.created);
90+
```
91+
92+
### Actions
93+
94+
```dart
95+
final res = await repo.actions(
96+
actionUriKey: 'publish',
97+
data: LaravelRestApiActionsBody(
98+
fields: [
99+
Action(name: 'published_at', value: DateTime.now().toIso8601String()),
100+
],
101+
),
102+
);
103+
104+
print(res.data); // impacted count
105+
```

‎content/2.sdk/3.factories.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Factories
3+
description: What each factory does and how to use it.
4+
---
5+
6+
# Factories
7+
8+
Factories are mixins that implement one Lomkit endpoint family. You mix in what you need per repository.
9+
10+
## SearchFactory<T>
11+
12+
- Endpoint: `POST {baseRoute}/search`
13+
- Returns: `RestApiResponse<List<T>>`
14+
15+
```dart
16+
class UsersRepository with SearchFactory<UserModel> {
17+
@override
18+
String get baseRoute => '/users';
19+
20+
@override
21+
RestApiClient get httpClient => client;
22+
23+
@override
24+
UserModel fromJson(Map<String, dynamic> json) => UserModel.fromJson(json);
25+
26+
@override
27+
void onCatchError(RestApiResponse? r, Object e, StackTrace s) {}
28+
}
29+
```
30+
31+
## DetailsFactory<T>
32+
33+
- Endpoint: depends on your backend route (`GET {baseRoute}/{id}` or `POST {baseRoute}/details`, etc.)
34+
- Returns: `RestApiResponse<T>`
35+
36+
> Check your project’s DetailsFactory implementation for the exact signature and route used.
37+
38+
## MutateFactory
39+
40+
- Endpoint: `POST {baseRoute}/mutate`
41+
- Returns: `RestApiResponse<LaravelRestApiMutateResponse>`
42+
43+
## ActionsFactory
44+
45+
- Endpoint: `POST {baseRoute}/actions/{actionUriKey}`
46+
- Returns: `RestApiResponse<int>` where `data` is `impacted`
47+
48+
## DeleteFactory<T>
49+
50+
- Endpoint: `DELETE {baseRoute}`
51+
- Body: `{ "resources": [ids...] }`
52+
- Returns: `RestApiResponse<List<T>>`
53+
54+
## RestoreFactory / ForceDeleteFactory
55+
56+
- Endpoints and signatures follow the same pattern as DeleteFactory.
57+
- Use when your backend enables soft deletes.

‎content/2.sdk/4.search-json.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Search JSON
3+
description: Build a Lomkit search payload (filters, includes, aggregates, instructions, pagination).
4+
---
5+
6+
# Search JSON
7+
8+
Search uses a structured JSON body under the `search` key.
9+
10+
## Full example
11+
12+
```dart
13+
final res = await repo.search(
14+
text: TextSearch(value: 'example'),
15+
page: 1,
16+
limit: 20,
17+
scopes: [Scope(name: 'active')],
18+
filters: [
19+
// Explicit null is supported
20+
Filter(field: 'status', operator: '=', value: null),
21+
],
22+
sorts: [Sort(field: 'created_at', direction: 'desc')],
23+
selects: [Select(field: 'id'), Select(field: 'name')],
24+
includes: [
25+
Include(
26+
relation: 'author',
27+
selects: [Select(field: 'id'), Select(field: 'name')],
28+
includes: [Include(relation: 'company')],
29+
),
30+
],
31+
aggregates: [
32+
Aggregate(relation: 'comments', type: 'count', field: 'id'),
33+
],
34+
instructions: [
35+
Instruction(
36+
name: 'customInstruction',
37+
fields: [
38+
InstructionField(field: 'flag', value: true),
39+
InstructionField(field: 'note', value: null),
40+
],
41+
),
42+
],
43+
);
44+
```
45+
46+
## Notes
47+
48+
- `Filter.value` can be `null` and will be sent explicitly in JSON.
49+
- Pagination uses `page` + `limit`.

‎content/2.sdk/5.mutate-json.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Mutate JSON
3+
description: Create/update resources and relations in a single request.
4+
---
5+
6+
# Mutate JSON
7+
8+
Mutate is designed for batched writes.
9+
10+
## Create / Update
11+
12+
```dart
13+
final body = LaravelRestApiMutateBody(
14+
mutate: [
15+
Mutation(
16+
operation: MutationOperation.create,
17+
attributes: {'name': 'New item'},
18+
),
19+
Mutation(
20+
operation: MutationOperation.update,
21+
key: 10,
22+
attributes: {'name': 'Updated name'},
23+
),
24+
],
25+
);
26+
27+
final res = await repo.mutate(body: body);
28+
print(res.data?.created);
29+
print(res.data?.updated);
30+
```
31+
32+
## Nested relations (grouped by table)
33+
34+
Relations must be grouped by table name, and `multipleRelation` becomes an array.
35+
36+
```dart
37+
final body = LaravelRestApiMutateBody(
38+
mutate: [
39+
Mutation(
40+
operation: MutationOperation.update,
41+
key: 10,
42+
attributes: {'name': 'Updated'},
43+
relations: [
44+
// 1:1 relation
45+
MutationRelation(
46+
table: 'author',
47+
relationType: RelationType.singleRelation,
48+
operation: MutationRelationOperation.attach,
49+
key: 1,
50+
),
51+
// 1:N or N:N relation
52+
MutationRelation(
53+
table: 'tags',
54+
relationType: RelationType.multipleRelation,
55+
operation: MutationRelationOperation.sync,
56+
key: 2,
57+
),
58+
MutationRelation(
59+
table: 'tags',
60+
relationType: RelationType.multipleRelation,
61+
operation: MutationRelationOperation.sync,
62+
key: 3,
63+
),
64+
],
65+
),
66+
],
67+
);
68+
69+
await repo.mutate(body: body);
70+
```

‎content/2.sdk/6.actions.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Actions
3+
description: Trigger server-side actions (bulk operations).
4+
---
5+
6+
# Actions
7+
8+
Actions run backend logic on a resource.
9+
10+
- Endpoint: `POST {baseRoute}/actions/{actionUriKey}`
11+
- Body: `{ "fields": [ { "name": "...", "value": "..." } ] }`
12+
13+
```dart
14+
final res = await repo.actions(
15+
actionUriKey: 'expire-items',
16+
data: LaravelRestApiActionsBody(
17+
fields: [
18+
Action(name: 'expires_at', value: '2025-12-31'),
19+
],
20+
),
21+
);
22+
23+
print(res.data); // impacted
24+
```

‎content/2.sdk/7.delete-restore-force-delete.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Delete, Restore, Force Delete
3+
description: Resource deletion lifecycle helpers.
4+
---
5+
6+
# Delete, Restore, Force Delete
7+
8+
## Delete
9+
10+
```dart
11+
final res = await repo.delete(resourceIds: [1, 2, 3]);
12+
print(res.data);
13+
```
14+
15+
## Restore (soft deletes)
16+
17+
> Available if your repository mixes in `RestoreFactory`.
18+
19+
```dart
20+
final res = await repo.restore(resourceIds: [1, 2]);
21+
```
22+
23+
## Force delete (permanent)
24+
25+
> Available if your repository mixes in `ForceDeleteFactory`.
26+
27+
```dart
28+
final res = await repo.forceDelete(resourceIds: [1, 2]);
29+
```

0 commit comments

Comments
 (0)