bunware.org
1---
2applyTo: "lib/api.dart"
3---
4
5# Copilot Instructions: Generate Typed Dart API Client for Grain Social Endpoints
6
7## Goal
8
9Generate a Dart API client for the Grain social endpoints, using the lexicon
10JSON files in `lexicons/social/grain` and its subfolders. Each endpoint should
11have:
12
13- Typed request and response models
14- API methods with correct parameters and return types
15- Documentation from the lexicon descriptions
16
17## Instructions for Copilot
18
191. **For each lexicon JSON file:**
20 - Parse the endpoint definition (`id`, `type`, `description`,
21 `parameters`/`input`, `output`).
22 - Generate a Dart class for request parameters/input.
23 - Generate a Dart class for response/output.
24 - Use the [freezed](https://pub.dev/packages/freezed) package to generate an
25 immutable model for each response type.
26 - Each model class should be created in a separate file in
27 `models/procedures`.
28 - Create a Dart method for the endpoint, with correct types and
29 documentation.
30 - Each API method should:
31 - Accept an `apiUrl` parameter as a prefix for requests (e.g.,
32 `$apiUrl/xrpc/${id}`).
33 - Pass the API token in the `Authorization` header for all requests.
34 - Use the endpoint URL format `/xrpc/${id}` (e.g.,
35 `/xrpc/social.grain.actor.getProfile`).
36
372. **Type Mapping:**
38 - JSON `string` → Dart `String`
39 - JSON `object` → Dart class
40 - JSON `array` → Dart `List<T>`
41 - JSON `integer` → Dart `int`
42 - JSON `boolean` → Dart `bool`
43 - JSON `*/*` (binary) → Dart `Uint8List` or `List<int>`
44
453. **API Method Example:**
46 ```dart
47 /// Get detailed profile view of an actor.
48 Future<ProfileViewDetailed> getProfile(String actor);
49
50 /// Create a comment.
51 Future<CommentResponse> createComment(CreateCommentRequest request);
52
53 /// Create a follow relationship.
54 Future<FollowResponse> createFollow(String subject);
55
56 /// Create a photo.
57 Future<PhotoResponse> createPhoto(Uint8List photoData);
58 ```
59
604. **Documentation:**
61 - Use the `description` field from the lexicon for method/class docs.
62
635. **Error Handling:**
64 - Generate error classes/types for API errors.
65
666. **Authentication:**
67 - Mark endpoints that require auth.
68
69## Reference
70
71Use all JSON files in `lexicons/social/grain` and subfolders. For each endpoint,
72use the schema references for response types if available.
73
74## Example Endpoints
75
76### Get Actor Profile
77
78- **ID:** `social.grain.actor.getProfile`
79- **Type:** Query
80- **Description:** Get detailed profile view of an actor. Does not require auth,
81 but contains relevant metadata with auth.
82- **Parameters:** `actor` (string, at-identifier)
83- **Response:** JSON, schema: `social.grain.actor.defs#profileViewDetailed`