@miragon/pulse-engine-client 0.0.0-bootstrap.0
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/README.md +110 -0
- package/package.json +15 -0
package/README.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# @miragon/pulse-engine-client
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@miragon/pulse-engine-client)
|
|
4
|
+
[](https://github.com/Miragon/pulse/actions/workflows/ci.yml)
|
|
5
|
+
[](https://miragon.github.io/pulse/)
|
|
6
|
+
|
|
7
|
+
A typed TypeScript client for the REST API of Camunda 7, CIB seven and Operaton.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @miragon/pulse-engine-client
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Overview
|
|
16
|
+
|
|
17
|
+
TypeScript client for the [CIB seven](https://cibseven.org/) REST API: an SDK
|
|
18
|
+
generated with [`@hey-api/openapi-ts`](https://heyapi.dev/), a client factory
|
|
19
|
+
with deadlines and engine errors, and the reads whose REST contract the SDK
|
|
20
|
+
defaults miss. There is no official TypeScript client for CIB seven; this
|
|
21
|
+
package fills that gap for Pulse and is usable by any CIB seven / Camunda 7
|
|
22
|
+
project. It has no runtime dependency. The pure engine REST rules (dates,
|
|
23
|
+
filters, sorting, variable writes, incident recovery) live in
|
|
24
|
+
[`@miragon/pulse-engine-core`](../engine-core/README.md), which this package
|
|
25
|
+
does not import.
|
|
26
|
+
|
|
27
|
+
## Exports
|
|
28
|
+
|
|
29
|
+
| Subpath | Contents |
|
|
30
|
+
| --------- | ----------------------------------------------------------------------------------------- |
|
|
31
|
+
| `.` | `createEngineClient` factory, `EngineRequestError`, the SDK-bound reads and batch reports |
|
|
32
|
+
| `./sdk` | Generated SDK, one typed function per REST operation |
|
|
33
|
+
| `./types` | Generated request/response types |
|
|
34
|
+
|
|
35
|
+
These three subpaths are the public API. The internal layout of the generated
|
|
36
|
+
output (`dist/generated/**`) is not: it may change with any `@hey-api/openapi-ts`
|
|
37
|
+
upgrade, so deep imports are deliberately not exported.
|
|
38
|
+
|
|
39
|
+
## Client behavior
|
|
40
|
+
|
|
41
|
+
SDK functions return the response payload directly (`responseStyle: "data"`)
|
|
42
|
+
and reject on HTTP error responses (`throwOnError: true`). Both options are
|
|
43
|
+
declared once in the generator config (`openapi-ts.config.ts`) and applied at
|
|
44
|
+
runtime through `createClientConfig` (`src/hey-api.ts`), which the generated
|
|
45
|
+
default client and `createEngineClient` share, so generated types and runtime
|
|
46
|
+
behavior always agree.
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import { createEngineClient } from "@miragon/pulse-engine-client"
|
|
50
|
+
import { getProcessDefinitions } from "@miragon/pulse-engine-client/sdk"
|
|
51
|
+
|
|
52
|
+
const client = createEngineClient({
|
|
53
|
+
baseUrl: "http://localhost:8410/engine-rest",
|
|
54
|
+
authType: "basic",
|
|
55
|
+
username: "demo",
|
|
56
|
+
password: "demo",
|
|
57
|
+
})
|
|
58
|
+
const definitions = await getProcessDefinitions({ client, query: { latestVersion: true } })
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Every `createEngineClient` client, whatever its auth type, rejects with an
|
|
62
|
+
`EngineRequestError` (an `Error` with `kind`, `httpStatus`, `type`,
|
|
63
|
+
`engineMessage`, `engineCode`, `engineId`) instead of the raw error body, with
|
|
64
|
+
a message that is safe and useful to show a model (engine text truncated, the
|
|
65
|
+
request's credentials masked):
|
|
66
|
+
`[404 InvalidRequestException] Process instance with id x does not exist (engine prod-a)`,
|
|
67
|
+
`engine prod-a unreachable (ECONNREFUSED)` (no connection: the engine never
|
|
68
|
+
saw the request), `connection to engine prod-a failed (ECONNRESET)` (dropped
|
|
69
|
+
mid-request; a write adds that it may still have been applied), or
|
|
70
|
+
`engine prod-a did not respond within 30000 ms (timeout)`. Pass `engineId` to
|
|
71
|
+
name the engine in those messages and `timeoutMs` to change the per-request
|
|
72
|
+
deadline (default 30 000 ms). `withCallerSignal(client, signal)` returns a view
|
|
73
|
+
whose reads (`GET`/`HEAD`/`OPTIONS`) also abort with the caller's signal;
|
|
74
|
+
writes never do, since aborting a started write cannot undo it.
|
|
75
|
+
|
|
76
|
+
The deadline lives in the client's `fetch`, so it binds each request after
|
|
77
|
+
every request interceptor. A custom `fetch` (per call or via `setConfig`)
|
|
78
|
+
replaces it, so wrap `client.getConfig().fetch` instead. Request interceptors
|
|
79
|
+
should mutate the request (`request.headers.set(…)`): one that returns a new
|
|
80
|
+
`Request` keeps the deadline, but can detach the caller's signal.
|
|
81
|
+
|
|
82
|
+
## OpenAPI spec: origin & refresh
|
|
83
|
+
|
|
84
|
+
The spec is checked in as `cibseven-open-api-doc.json` (currently reporting
|
|
85
|
+
`info.version` **2.1.2**). It originates from the engine's published OpenAPI
|
|
86
|
+
artifact `org.cibseven.bpm:cibseven-engine-rest-openapi` (a jar containing
|
|
87
|
+
`openapi.json`); Maven Central publishes the minor releases (2.1.0, 2.2.0, …).
|
|
88
|
+
The running engine does not serve its spec over HTTP, so the artifact is the
|
|
89
|
+
canonical source.
|
|
90
|
+
|
|
91
|
+
To refresh:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
pnpm spec:refresh <version> # downloads + extracts the spec, e.g. pnpm spec:refresh 2.2.0
|
|
95
|
+
pnpm generate # regenerate src/generated from the new spec
|
|
96
|
+
git diff # review spec + SDK changes, run the repo verification suite
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Commit the spec and the regenerated output together: `src/generated/` is
|
|
100
|
+
checked in and CI assumes it matches the spec.
|
|
101
|
+
|
|
102
|
+
## The SDK-bound reads
|
|
103
|
+
|
|
104
|
+
`src/engine-contract/` holds the reads whose REST contract differs from the SDK
|
|
105
|
+
defaults: the `text/plain`-only stacktrace and error-details endpoints
|
|
106
|
+
(`fetchJobStacktrace`, `fetchExternalTaskErrorDetails`, `null` on a 404),
|
|
107
|
+
variable reads with `deserializeValues=false` (`readProcessInstanceVariables`,
|
|
108
|
+
`readTaskVariables`) and `readBatch`, which falls back from the runtime
|
|
109
|
+
statistics to the history record. The MCP tools' input schemas live in
|
|
110
|
+
`@miragon/pulse-engine-connector` next to its tools.
|
package/package.json
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@miragon/pulse-engine-client",
|
|
3
|
+
"version": "0.0.0-bootstrap.0",
|
|
4
|
+
"description": "Placeholder that binds the package to GitHub trusted publishing. Releases start with 0.25.0.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/Miragon/pulse.git",
|
|
9
|
+
"directory": "packages/connectors/engine/engine-client"
|
|
10
|
+
},
|
|
11
|
+
"publishConfig": {
|
|
12
|
+
"access": "public",
|
|
13
|
+
"tag": "bootstrap"
|
|
14
|
+
}
|
|
15
|
+
}
|