Skip to content

Commit 9adf594

Browse files
hotlonghotlong
authored
Merge pull request #776 from objectstack-ai/copilot/complete-marketplace-package-lifecycle-again
2 parents 50a6cb8 + 903c959 commit 9adf594

38 files changed

Lines changed: 2696 additions & 315 deletions

‎ROADMAP.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -696,6 +696,7 @@ Final polish and advanced features.
696696
- [x] Dependency resolution protocol — conflict detection, topological install ordering
697697
- [x] Namespace collision detection — registry entries, conflict errors
698698
- [x] Upgrade migration context — version context for onUpgrade hooks, upgrade history
699+
- [x] Protocol `.describe()` completeness — all marketplace lifecycle schemas fully annotated
699700
- [ ] Plugin marketplace runtime — publish, discover, install community plugins
700701
- [ ] CLI: `os plugin build` — generate `.tgz` per PackageArtifactSchema
701702
- [ ] CLI: `os plugin validate` — verify artifact structure, checksums, signatures

‎content/docs/references/api/automation-api.mdx‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
---
2+
title: Automation Api
3+
description: Automation Api protocol schemas
4+
---
5+
6+
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}
7+
8+
Automation API Protocol
9+
10+
Defines REST CRUD endpoint schemas for managing automation flows,
11+
12+
triggering executions, and querying execution history.
13+
14+
Base path: /api/automation
15+
16+
@example Endpoints
17+
18+
GET /api/automation — List flows
19+
20+
GET /api/automation/:name — Get flow
21+
22+
POST /api/automation — Create flow
23+
24+
PUT /api/automation/:name — Update flow
25+
26+
DELETE /api/automation/:name — Delete flow
27+
28+
POST /api/automation/:name/trigger — Trigger flow execution
29+
30+
POST /api/automation/:name/toggle — Enable/disable flow
31+
32+
GET /api/automation/:name/runs — List execution runs
33+
34+
GET /api/automation/:name/runs/:runId — Get single execution run
35+
36+
<Callout type="info">
37+
**Source:** `packages/spec/src/api/automation-api.zod.ts`
38+
</Callout>
39+
40+
## TypeScript Usage
41+
42+
```typescript
43+
import { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, CreateFlowRequest, CreateFlowResponse, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetFlowResponse, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse, UpdateFlowRequest, UpdateFlowResponse } from '@objectstack/spec/api';
44+
import type { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, CreateFlowRequest, CreateFlowResponse, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetFlowResponse, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse, UpdateFlowRequest, UpdateFlowResponse } from '@objectstack/spec/api';
45+
46+
// Validate data
47+
const result = AutomationApiErrorCode.parse(data);
48+
```
49+
50+
---
51+
52+
## AutomationApiErrorCode
53+
54+
### Allowed Values
55+
56+
* `flow_not_found`
57+
* `flow_already_exists`
58+
* `flow_validation_failed`
59+
* `flow_disabled`
60+
* `execution_not_found`
61+
* `execution_failed`
62+
* `execution_timeout`
63+
* `node_executor_not_found`
64+
* `concurrent_execution_limit`
65+
66+
67+
---
68+
69+
## AutomationFlowPathParams
70+
71+
### Properties
72+
73+
| Property | Type | Required | Description |
74+
| :--- | :--- | :--- | :--- |
75+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
76+
77+
78+
---
79+
80+
## AutomationRunPathParams
81+
82+
### Properties
83+
84+
| Property | Type | Required | Description |
85+
| :--- | :--- | :--- | :--- |
86+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
87+
| **runId** | `string` | ✅ | Execution run ID |
88+
89+
90+
---
91+
92+
## CreateFlowRequest
93+
94+
### Properties
95+
96+
| Property | Type | Required | Description |
97+
| :--- | :--- | :--- | :--- |
98+
| **name** | `string` | ✅ | Machine name |
99+
| **label** | `string` | ✅ | Flow label |
100+
| **description** | `string` | optional | |
101+
| **version** | `integer` | ✅ | Version number |
102+
| **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | ✅ | Deployment status |
103+
| **template** | `boolean` | ✅ | Is logic template (Subflow) |
104+
| **type** | `Enum<'autolaunched' \| 'record_change' \| 'schedule' \| 'screen' \| 'api'>` | ✅ | Flow type |
105+
| **variables** | `Object[]` | optional | Flow variables |
106+
| **nodes** | `Object[]` | ✅ | Flow nodes |
107+
| **edges** | `Object[]` | ✅ | Flow connections |
108+
| **active** | `boolean` | ✅ | Is active (Deprecated: use status) |
109+
| **runAs** | `Enum<'system' \| 'user'>` | ✅ | Execution context |
110+
| **errorHandling** | `Object` | optional | Flow-level error handling configuration |
111+
112+
113+
---
114+
115+
## CreateFlowResponse
116+
117+
### Properties
118+
119+
| Property | Type | Required | Description |
120+
| :--- | :--- | :--- | :--- |
121+
| **success** | `boolean` | ✅ | Operation success status |
122+
| **error** | `Object` | optional | Error details if success is false |
123+
| **meta** | `Object` | optional | Response metadata |
124+
| **data** | `Object` | ✅ | The created flow definition |
125+
126+
127+
---
128+
129+
## DeleteFlowRequest
130+
131+
### Properties
132+
133+
| Property | Type | Required | Description |
134+
| :--- | :--- | :--- | :--- |
135+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
136+
137+
138+
---
139+
140+
## DeleteFlowResponse
141+
142+
### Properties
143+
144+
| Property | Type | Required | Description |
145+
| :--- | :--- | :--- | :--- |
146+
| **success** | `boolean` | ✅ | Operation success status |
147+
| **error** | `Object` | optional | Error details if success is false |
148+
| **meta** | `Object` | optional | Response metadata |
149+
| **data** | `Object` | ✅ | |
150+
151+
152+
---
153+
154+
## FlowSummary
155+
156+
### Properties
157+
158+
| Property | Type | Required | Description |
159+
| :--- | :--- | :--- | :--- |
160+
| **name** | `string` | ✅ | Flow machine name |
161+
| **label** | `string` | ✅ | Flow display label |
162+
| **type** | `string` | ✅ | Flow type |
163+
| **status** | `string` | ✅ | Flow deployment status |
164+
| **version** | `integer` | ✅ | Flow version number |
165+
| **enabled** | `boolean` | ✅ | Whether the flow is enabled for execution |
166+
| **nodeCount** | `integer` | optional | Number of nodes in the flow |
167+
| **lastRunAt** | `string` | optional | Last execution timestamp |
168+
169+
170+
---
171+
172+
## GetFlowRequest
173+
174+
### Properties
175+
176+
| Property | Type | Required | Description |
177+
| :--- | :--- | :--- | :--- |
178+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
179+
180+
181+
---
182+
183+
## GetFlowResponse
184+
185+
### Properties
186+
187+
| Property | Type | Required | Description |
188+
| :--- | :--- | :--- | :--- |
189+
| **success** | `boolean` | ✅ | Operation success status |
190+
| **error** | `Object` | optional | Error details if success is false |
191+
| **meta** | `Object` | optional | Response metadata |
192+
| **data** | `Object` | ✅ | Full flow definition |
193+
194+
195+
---
196+
197+
## GetRunRequest
198+
199+
### Properties
200+
201+
| Property | Type | Required | Description |
202+
| :--- | :--- | :--- | :--- |
203+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
204+
| **runId** | `string` | ✅ | Execution run ID |
205+
206+
207+
---
208+
209+
## GetRunResponse
210+
211+
### Properties
212+
213+
| Property | Type | Required | Description |
214+
| :--- | :--- | :--- | :--- |
215+
| **success** | `boolean` | ✅ | Operation success status |
216+
| **error** | `Object` | optional | Error details if success is false |
217+
| **meta** | `Object` | optional | Response metadata |
218+
| **data** | `Object` | ✅ | Full execution log with step details |
219+
220+
221+
---
222+
223+
## ListFlowsRequest
224+
225+
### Properties
226+
227+
| Property | Type | Required | Description |
228+
| :--- | :--- | :--- | :--- |
229+
| **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional | Filter by flow status |
230+
| **type** | `Enum<'autolaunched' \| 'record_change' \| 'schedule' \| 'screen' \| 'api'>` | optional | Filter by flow type |
231+
| **limit** | `integer` | ✅ | Maximum number of flows to return |
232+
| **cursor** | `string` | optional | Cursor for pagination |
233+
234+
235+
---
236+
237+
## ListFlowsResponse
238+
239+
### Properties
240+
241+
| Property | Type | Required | Description |
242+
| :--- | :--- | :--- | :--- |
243+
| **success** | `boolean` | ✅ | Operation success status |
244+
| **error** | `Object` | optional | Error details if success is false |
245+
| **meta** | `Object` | optional | Response metadata |
246+
| **data** | `Object` | ✅ | |
247+
248+
249+
---
250+
251+
## ListRunsRequest
252+
253+
### Properties
254+
255+
| Property | Type | Required | Description |
256+
| :--- | :--- | :--- | :--- |
257+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
258+
| **status** | `Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying'>` | optional | Filter by execution status |
259+
| **limit** | `integer` | ✅ | Maximum number of runs to return |
260+
| **cursor** | `string` | optional | Cursor for pagination |
261+
262+
263+
---
264+
265+
## ListRunsResponse
266+
267+
### Properties
268+
269+
| Property | Type | Required | Description |
270+
| :--- | :--- | :--- | :--- |
271+
| **success** | `boolean` | ✅ | Operation success status |
272+
| **error** | `Object` | optional | Error details if success is false |
273+
| **meta** | `Object` | optional | Response metadata |
274+
| **data** | `Object` | ✅ | |
275+
276+
277+
---
278+
279+
## ToggleFlowRequest
280+
281+
### Properties
282+
283+
| Property | Type | Required | Description |
284+
| :--- | :--- | :--- | :--- |
285+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
286+
| **enabled** | `boolean` | ✅ | Whether to enable (true) or disable (false) the flow |
287+
288+
289+
---
290+
291+
## ToggleFlowResponse
292+
293+
### Properties
294+
295+
| Property | Type | Required | Description |
296+
| :--- | :--- | :--- | :--- |
297+
| **success** | `boolean` | ✅ | Operation success status |
298+
| **error** | `Object` | optional | Error details if success is false |
299+
| **meta** | `Object` | optional | Response metadata |
300+
| **data** | `Object` | ✅ | |
301+
302+
303+
---
304+
305+
## TriggerFlowRequest
306+
307+
### Properties
308+
309+
| Property | Type | Required | Description |
310+
| :--- | :--- | :--- | :--- |
311+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
312+
| **record** | `Record<string, any>` | optional | Record that triggered the automation |
313+
| **object** | `string` | optional | Object name the record belongs to |
314+
| **event** | `string` | optional | Trigger event type |
315+
| **userId** | `string` | optional | User who triggered the automation |
316+
| **params** | `Record<string, any>` | optional | Additional contextual data |
317+
318+
319+
---
320+
321+
## TriggerFlowResponse
322+
323+
### Properties
324+
325+
| Property | Type | Required | Description |
326+
| :--- | :--- | :--- | :--- |
327+
| **success** | `boolean` | ✅ | Operation success status |
328+
| **error** | `Object` | optional | Error details if success is false |
329+
| **meta** | `Object` | optional | Response metadata |
330+
| **data** | `Object` | ✅ | |
331+
332+
333+
---
334+
335+
## UpdateFlowRequest
336+
337+
### Properties
338+
339+
| Property | Type | Required | Description |
340+
| :--- | :--- | :--- | :--- |
341+
| **name** | `string` | ✅ | Flow machine name (snake_case) |
342+
| **definition** | `Object` | ✅ | Partial flow definition to update |
343+
344+
345+
---
346+
347+
## UpdateFlowResponse
348+
349+
### Properties
350+
351+
| Property | Type | Required | Description |
352+
| :--- | :--- | :--- | :--- |
353+
| **success** | `boolean` | ✅ | Operation success status |
354+
| **error** | `Object` | optional | Error details if success is false |
355+
| **meta** | `Object` | optional | Response metadata |
356+
| **data** | `Object` | ✅ | The updated flow definition |
357+
358+
359+
---
360+

‎content/docs/references/api/discovery.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ const result = ApiRoutes.parse(data);
6161
| **routes** | `Object` | ✅ | |
6262
| **locale** | `Object` | ✅ | |
6363
| **services** | `Record<string, Object>` | ✅ | Per-service availability map keyed by CoreServiceName |
64+
| **capabilities** | `Record<string, Object>` | optional | Hierarchical capability descriptors for frontend intelligent adaptation |
65+
| **schemaDiscovery** | `Object` | optional | Schema discovery endpoints for API toolchain integration |
6466
| **metadata** | `Record<string, any>` | optional | Custom metadata key-value pairs for extensibility |
6567

6668

@@ -76,7 +78,9 @@ const result = ApiRoutes.parse(data);
7678
| **status** | `Enum<'available' \| 'unavailable' \| 'degraded' \| 'stub'>` | ✅ | available = fully operational, unavailable = not installed, degraded = partial, stub = placeholder that throws |
7779
| **route** | `string` | optional | e.g. /api/v1/analytics |
7880
| **provider** | `string` | optional | e.g. "objectql", "plugin-redis", "driver-memory" |
81+
| **version** | `string` | optional | Semantic version of the service implementation (e.g. "3.0.6") |
7982
| **message** | `string` | optional | e.g. "Install plugin-workflow to enable" |
83+
| **rateLimit** | `Object` | optional | Rate limit and quota info for this service |
8084

8185

8286
---

0 commit comments

Comments
 (0)