@harperfast/template-vue-studio 1.13.5 → 1.13.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
- package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/.agents/skills/harper-mcp/AGENTS.md +228 -155
- package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
- package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/agent/skills/harper-mcp/AGENTS.md +228 -155
- package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/package.json +1 -1
- package/skills-lock.json +2 -2
|
@@ -12,29 +12,29 @@ metadata:
|
|
|
12
12
|
- reference/v5/rest/overview.md#Content Types
|
|
13
13
|
- reference/v5/rest/overview.md#OpenAPI
|
|
14
14
|
- reference/v5/rest/websockets.md
|
|
15
|
-
sourceCommit:
|
|
16
|
-
inputHash:
|
|
15
|
+
sourceCommit: 0a29827da61afe7fff40ee8de87e1d4c2c286bea
|
|
16
|
+
inputHash: 0672da4654ca1a34
|
|
17
17
|
---
|
|
18
18
|
|
|
19
|
-
# Automatic APIs
|
|
19
|
+
# Automatic REST and WebSocket APIs
|
|
20
20
|
|
|
21
|
-
Instructions for the agent to follow when
|
|
21
|
+
Instructions for the agent to follow when exposing Harper tables and custom resources as REST and WebSocket endpoints using Harper's automatically generated API layer.
|
|
22
22
|
|
|
23
23
|
**Instead of:** Hand-written CRUD routes (Express, Fastify, Next.js API routes). Use this rule rather than adding that service. See `harper-architecture`.
|
|
24
24
|
|
|
25
25
|
## When to Use
|
|
26
26
|
|
|
27
|
-
Apply this rule when enabling HTTP REST
|
|
27
|
+
Apply this rule when enabling HTTP REST access to Harper tables, when configuring WebSocket subscriptions on resource paths, or when customizing how exported resources respond to standard HTTP methods. Use it any time you need to wire up `rest: true`, handle conditional requests, or implement a `connect()` handler.
|
|
28
28
|
|
|
29
29
|
## How It Works
|
|
30
30
|
|
|
31
|
-
1. **Enable the REST plugin** by adding `rest: true` to
|
|
31
|
+
1. **Enable the REST plugin** by adding `rest: true` to the application's `config.yaml`:
|
|
32
32
|
|
|
33
33
|
```yaml
|
|
34
34
|
rest: true
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
Additional options:
|
|
38
38
|
|
|
39
39
|
```yaml
|
|
40
40
|
rest:
|
|
@@ -43,7 +43,9 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
|
|
|
43
43
|
exactCount: true # opt in to Prefer: count=exact scans (off by default)
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
A component directory with no `config.yaml` at all inherits a built-in default that enables `rest` and loads `*.graphql` from the component root. As soon as a `config.yaml` exists it is used verbatim — omitting `rest` turns REST off. Always write `rest: true` when adding a config file.
|
|
47
|
+
|
|
48
|
+
2. **Export the table in the schema** using `@export`. Tables are not exported by default.
|
|
47
49
|
|
|
48
50
|
```graphql
|
|
49
51
|
type Product @table @export {
|
|
@@ -53,41 +55,76 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
|
|
|
53
55
|
}
|
|
54
56
|
```
|
|
55
57
|
|
|
56
|
-
|
|
58
|
+
Reference the schema file from `config.yaml`:
|
|
59
|
+
|
|
60
|
+
```yaml
|
|
61
|
+
graphqlSchema:
|
|
62
|
+
files: schema.graphql
|
|
63
|
+
rest: true
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Both `@export` and `rest: true` are required. Without `@export`, no REST route is registered and callers receive `404`. Without REST enabled, even an exported table does not respond to HTTP requests.
|
|
67
|
+
|
|
68
|
+
3. **Understand the auto-generated endpoints**. With `Product` exported, Harper registers these routes on the application HTTP server port (default `9926`) with no handler code required:
|
|
69
|
+
|
|
70
|
+
| Endpoint | Description |
|
|
71
|
+
| ---------------------------- | --------------------------------------------------------------------------- |
|
|
72
|
+
| `GET /Product` | Resource description (table name, database, attributes) |
|
|
73
|
+
| `GET /Product/` | Record collection; append query parameters to filter/sort/page |
|
|
74
|
+
| `GET /Product/{id}` | Single record by primary key; `404` if not found |
|
|
75
|
+
| `GET /Product/{id}.property` | Single declared property of one record |
|
|
76
|
+
| `POST /Product/` | Creates a record; responds `201`; primary key returned in `Location` header |
|
|
77
|
+
| `PUT /Product/{id}` | Creates or replaces the record at `{id}` (upsert) |
|
|
78
|
+
| `PATCH /Product/{id}` | Shallow-merges body into existing record |
|
|
79
|
+
| `DELETE /Product/{id}` | Deletes the record at `{id}` |
|
|
80
|
+
| `DELETE /Product/?query` | Deletes every record matching the query |
|
|
57
81
|
|
|
58
|
-
|
|
82
|
+
The trailing slash is significant: `/Product` addresses the resource itself; `/Product/` addresses its record collection.
|
|
59
83
|
|
|
60
|
-
|
|
61
|
-
| ---------------------------- | ------------------------------------------------------------------------------------ |
|
|
62
|
-
| `GET /Product` | Resource description — table name, database, declared attributes |
|
|
63
|
-
| `GET /Product/` | Record collection; append query parameters to filter, sort, page |
|
|
64
|
-
| `GET /Product/{id}` | Single record by primary key; `404` if not found |
|
|
65
|
-
| `GET /Product/{id}.property` | Single declared property of one record |
|
|
66
|
-
| `POST /Product/` | Creates a record; responds `201`; primary key returned in `Location` header |
|
|
67
|
-
| `PUT /Product/{id}` | Creates or replaces the record at `{id}` (upsert); omitted properties are removed |
|
|
68
|
-
| `PATCH /Product/{id}` | Shallow-merges body into existing record; unspecified top-level properties preserved |
|
|
69
|
-
| `DELETE /Product/{id}` | Deletes the record at `{id}` |
|
|
70
|
-
| `DELETE /Product/?query` | Deletes every record matching the query |
|
|
71
|
-
- `HEAD` is served exactly as `GET` with the response body omitted. `QUERY` is accepted on the collection path (`QUERY /Product/`) and runs a search taken from the request body rather than the URL.
|
|
84
|
+
4. **Understand the URL structure**. Harper follows a consistent URL pattern across all resources:
|
|
72
85
|
|
|
73
|
-
|
|
86
|
+
| Path | Description |
|
|
87
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
88
|
+
| `/my-resource` | Root path — returns a description of the resource (e.g., table metadata) |
|
|
89
|
+
| `/my-resource/` | Trailing slash indicates a collection — represents all records; append query parameters to search |
|
|
90
|
+
| `/my-resource/record-id` | A specific record identified by its primary key |
|
|
91
|
+
| `/my-resource/record-id/` | Trailing slash — the collection of records with the given id prefix |
|
|
92
|
+
| `/my-resource/record-id/with/multiple/parts` | Record id with multiple path segments |
|
|
74
93
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
94
|
+
5. **Handle HTTP methods correctly**:
|
|
95
|
+
- **GET** — Retrieves a record or collection. Use `GET /MyTable/123` for a single record, `GET /MyTable/?name=Harper` for a filtered collection. The `.msgpack` suffix (along with `.json`, `.cbor`, `.csv`) is a reserved content-type selector and takes precedence over property access via dot syntax.
|
|
96
|
+
- **POST** — Creates a record. The new record's primary key is returned in the `Location` response header. A `POST` to a key that already exists fails with `409`.
|
|
97
|
+
- **PUT** — Upserts a record. The stored record matches the body exactly; omitted properties are removed. Harper always re-stamps an `@updatedTime` attribute and preserves `@createdTime`.
|
|
98
|
+
- **PATCH** — Shallow-merges the body. Top-level unspecified properties are preserved; nested objects in the body replace the stored sub-object wholesale.
|
|
99
|
+
- **DELETE** — Deletes by id or by query. `DELETE /MyTable/` with no query parameters deletes every record.
|
|
81
100
|
|
|
82
|
-
|
|
101
|
+
6. **Use conditional requests for caching**. GET responses include an `ETag` header. Clients send `If-None-Match` on subsequent requests; if the record is unchanged Harper returns `304 Not Modified` with no body.
|
|
83
102
|
|
|
84
|
-
|
|
103
|
+
7. **Set the `Accept` header** to request a specific response format. Use `Content-Type` for request bodies. See [querying-rest-apis.md](querying-rest-apis.md) for the full query syntax and content-type details.
|
|
85
104
|
|
|
86
|
-
|
|
105
|
+
8. **Use WebSocket subscriptions** on the same resource paths. WebSocket support is enabled automatically with `rest: true`. Connecting to a resource URL subscribes to change events:
|
|
87
106
|
|
|
88
|
-
|
|
107
|
+
```javascript
|
|
108
|
+
let ws = new WebSocket('wss://server/my-resource/341');
|
|
109
|
+
ws.onmessage = (event) => {
|
|
110
|
+
let data = JSON.parse(event.data);
|
|
111
|
+
};
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Disable WebSocket support without disabling REST:
|
|
115
|
+
|
|
116
|
+
```yaml
|
|
117
|
+
rest:
|
|
118
|
+
webSocket: false
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
For MQTT over WebSockets, set the sub-protocol header:
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
Sec-WebSocket-Protocol: mqtt
|
|
125
|
+
```
|
|
89
126
|
|
|
90
|
-
9. **Implement a custom `connect()` handler**
|
|
127
|
+
9. **Implement a custom `connect()` handler** on a resource class to control WebSocket behavior. The method must return an async iterable producing messages to send to the client:
|
|
91
128
|
|
|
92
129
|
```javascript
|
|
93
130
|
export class Echo extends Resource {
|
|
@@ -99,28 +136,25 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
|
|
|
99
136
|
}
|
|
100
137
|
```
|
|
101
138
|
|
|
102
|
-
10. **
|
|
139
|
+
10. **Control OpenAPI visibility**. Every non-hidden exported resource is included in the generated OpenAPI document at `GET /openapi`. To exclude a type from the OpenAPI document, mark it `@hidden` in the schema:
|
|
103
140
|
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
};
|
|
141
|
+
```graphql
|
|
142
|
+
type Secret @table @export @hidden {
|
|
143
|
+
id: Long @primaryKey
|
|
144
|
+
}
|
|
109
145
|
```
|
|
110
146
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
11. **Use MQTT over WebSockets** by setting the sub-protocol header:
|
|
147
|
+
Or set `static hidden = true` on a programmatic resource class:
|
|
114
148
|
|
|
149
|
+
```javascript
|
|
150
|
+
export class Secret extends Resource {
|
|
151
|
+
static hidden = true;
|
|
152
|
+
}
|
|
115
153
|
```
|
|
116
|
-
Sec-WebSocket-Protocol: mqtt
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
12. **Specify response format** using the `Accept` header. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors on property paths and take precedence over property names.
|
|
120
154
|
|
|
121
155
|
## Examples
|
|
122
156
|
|
|
123
|
-
**
|
|
157
|
+
**Full schema and config setup:**
|
|
124
158
|
|
|
125
159
|
```graphql
|
|
126
160
|
# schema.graphql
|
|
@@ -138,77 +172,78 @@ graphqlSchema:
|
|
|
138
172
|
rest: true
|
|
139
173
|
```
|
|
140
174
|
|
|
141
|
-
**Conditional GET with
|
|
175
|
+
**Conditional GET with caching:**
|
|
142
176
|
|
|
143
|
-
```
|
|
177
|
+
```
|
|
144
178
|
GET /Product/123
|
|
145
|
-
If-None-Match: "
|
|
179
|
+
If-None-Match: "abc123etag"
|
|
146
180
|
```
|
|
147
181
|
|
|
148
182
|
Response when unchanged:
|
|
149
183
|
|
|
150
184
|
```
|
|
151
185
|
HTTP/1.1 304 Not Modified
|
|
152
|
-
ETag: "
|
|
186
|
+
ETag: "abc123etag"
|
|
153
187
|
```
|
|
154
188
|
|
|
155
189
|
**POST and read the Location header:**
|
|
156
190
|
|
|
157
|
-
```
|
|
191
|
+
```
|
|
158
192
|
POST /Product/
|
|
159
193
|
Content-Type: application/json
|
|
160
194
|
|
|
161
|
-
{ "name": "Widget" }
|
|
195
|
+
{ "name": "Widget", "price": 9.99 }
|
|
162
196
|
```
|
|
163
197
|
|
|
198
|
+
Response:
|
|
199
|
+
|
|
164
200
|
```
|
|
165
201
|
HTTP/1.1 201 Created
|
|
166
202
|
Location: 7f3a9c
|
|
167
203
|
```
|
|
168
204
|
|
|
169
|
-
**PATCH
|
|
205
|
+
**PATCH shallow merge:**
|
|
170
206
|
|
|
171
|
-
```
|
|
207
|
+
```
|
|
172
208
|
PATCH /Product/123
|
|
173
209
|
Content-Type: application/json
|
|
174
210
|
|
|
175
|
-
{ "
|
|
211
|
+
{ "price": 12.99 }
|
|
176
212
|
```
|
|
177
213
|
|
|
178
|
-
|
|
214
|
+
Preserves `name` and all other top-level properties; replaces any nested object in `price` wholesale.
|
|
215
|
+
|
|
216
|
+
**Custom WebSocket connect handler with timer:**
|
|
179
217
|
|
|
180
218
|
```javascript
|
|
181
|
-
export class
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
yield message; // echo each message back
|
|
185
|
-
}
|
|
186
|
-
}
|
|
187
|
-
}
|
|
188
|
-
```
|
|
219
|
+
export class Example extends Resource {
|
|
220
|
+
connect(incomingMessages) {
|
|
221
|
+
let outgoingMessages = super.connect();
|
|
189
222
|
|
|
190
|
-
|
|
223
|
+
let timer = setInterval(() => {
|
|
224
|
+
outgoingMessages.send({ greeting: 'hi again!' });
|
|
225
|
+
}, 1000);
|
|
191
226
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
}
|
|
196
|
-
```
|
|
227
|
+
incomingMessages.on('data', (message) => {
|
|
228
|
+
outgoingMessages.send(message);
|
|
229
|
+
});
|
|
197
230
|
|
|
198
|
-
|
|
231
|
+
outgoingMessages.on('close', () => {
|
|
232
|
+
clearInterval(timer);
|
|
233
|
+
});
|
|
199
234
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
static hidden = true;
|
|
235
|
+
return outgoingMessages;
|
|
236
|
+
}
|
|
203
237
|
}
|
|
204
238
|
```
|
|
205
239
|
|
|
206
240
|
## Notes
|
|
207
241
|
|
|
208
|
-
-
|
|
209
|
-
- `
|
|
210
|
-
-
|
|
211
|
-
- PATCH merge is
|
|
212
|
-
-
|
|
213
|
-
-
|
|
214
|
-
- See [
|
|
242
|
+
- The trailing slash is always significant: `/Product` is the resource descriptor; `/Product/` is the record collection. `POST /Product` (no slash) returns `404`.
|
|
243
|
+
- `HEAD` is served exactly as `GET` with the response body omitted. `QUERY` is accepted on the collection path (`QUERY /Product/`) and runs a search taken from the request body rather than the URL.
|
|
244
|
+
- `PUT` always forces the primary key to match the `{id}` in the URL, re-stamps `@updatedTime`, and preserves `@createdTime` from the original record.
|
|
245
|
+
- PATCH merge is shallow only. A nested object in the body replaces the entire stored sub-object; omitted nested properties are lost.
|
|
246
|
+
- Server-Sent Events subscriptions are served on the same paths, negotiated via `Accept: text/event-stream`. They are not affected by the `webSocket` option.
|
|
247
|
+
- Leaving `@export` on the schema while also exporting a same-named subclass produces conflicting endpoints. When a JavaScript subclass should own the URL, omit `@export` from the schema and export the class instead.
|
|
248
|
+
- See [real-time-apps.md](real-time-apps.md) for patterns around WebSocket and event-driven resource design.
|
|
249
|
+
- See [querying-rest-apis.md](querying-rest-apis.md) for filtering, sorting, pagination, and content-type details.
|