@powerhousedao/pieces-framework 6.2.3-dev.100
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/LICENSE +59 -0
- package/README.md +372 -0
- package/UPSTREAM.md +223 -0
- package/dist/action-C-O5Jgbl.d.ts +12883 -0
- package/dist/action-C-O5Jgbl.d.ts.map +1 -0
- package/dist/authentication-f4cep7Po.js +249 -0
- package/dist/authentication-f4cep7Po.js.map +1 -0
- package/dist/block-type.d.ts +25 -0
- package/dist/block-type.d.ts.map +1 -0
- package/dist/block-type.js +71 -0
- package/dist/block-type.js.map +1 -0
- package/dist/common.d.ts +289 -0
- package/dist/common.d.ts.map +1 -0
- package/dist/common.js +852 -0
- package/dist/common.js.map +1 -0
- package/dist/host.d.ts +99 -0
- package/dist/host.d.ts.map +1 -0
- package/dist/host.js +731 -0
- package/dist/host.js.map +1 -0
- package/dist/index-DZ0aWCvr.d.ts +5588 -0
- package/dist/index-DZ0aWCvr.d.ts.map +1 -0
- package/dist/index.d.ts +1438 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1896 -0
- package/dist/index.js.map +1 -0
- package/dist/input-BHkj_oP5.js +321 -0
- package/dist/input-BHkj_oP5.js.map +1 -0
- package/dist/markdown-property-DMfHjEiL.js +288 -0
- package/dist/markdown-property-DMfHjEiL.js.map +1 -0
- package/dist/workflow.d.ts +156 -0
- package/dist/workflow.d.ts.map +1 -0
- package/dist/workflow.js +451 -0
- package/dist/workflow.js.map +1 -0
- package/package.json +98 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Powerhouse Inc.
|
|
4
|
+
|
|
5
|
+
Applies to everything in this package outside upstream/ and test/upstream/
|
|
6
|
+
(src/, scripts/, test/, the build and package files).
|
|
7
|
+
|
|
8
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
9
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
10
|
+
in the Software without restriction, including without limitation the rights
|
|
11
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
12
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
13
|
+
furnished to do so, subject to the following conditions:
|
|
14
|
+
|
|
15
|
+
The above copyright notice and this permission notice shall be included in all
|
|
16
|
+
copies or substantial portions of the Software.
|
|
17
|
+
|
|
18
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
19
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
20
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
21
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
22
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
23
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
24
|
+
SOFTWARE.
|
|
25
|
+
|
|
26
|
+
--------------------------------------------------------------------------------
|
|
27
|
+
|
|
28
|
+
The code under upstream/ and test/upstream/ is vendored from
|
|
29
|
+
https://github.com/activepieces/activepieces (packages/pieces/framework,
|
|
30
|
+
packages/pieces/common, packages/core/piece-types and packages/core/utils, none
|
|
31
|
+
of which lie under the "packages/ee/" carve-out) and stays under its original
|
|
32
|
+
license, reproduced verbatim below. The exact tag and commit are recorded in
|
|
33
|
+
upstream/MANIFEST.json.
|
|
34
|
+
|
|
35
|
+
Copyright (c) 2020-2024 Activepieces Inc.
|
|
36
|
+
|
|
37
|
+
Portions of this software are licensed as follows:
|
|
38
|
+
|
|
39
|
+
* All content that resides under the "packages/ee/" and "packages/server/api/src/app/ee" directory of this repository, if that directory exists, is licensed under the license defined in packages/ee/LICENSE
|
|
40
|
+
* All third party components incorporated into the Activepieces Inc Software are licensed under the original license provided by the owner of the applicable component.
|
|
41
|
+
* Content outside of the above mentioned directories or restrictions above is available under the "MIT Expat" license as defined below.
|
|
42
|
+
|
|
43
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
44
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
45
|
+
in the Software without restriction, including without limitation the rights
|
|
46
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
47
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
48
|
+
furnished to do so, subject to the following conditions:
|
|
49
|
+
|
|
50
|
+
The above copyright notice and this permission notice shall be included in all
|
|
51
|
+
copies or substantial portions of the Software.
|
|
52
|
+
|
|
53
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
54
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
55
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
56
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
57
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
58
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
59
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
# @powerhousedao/pieces-framework
|
|
2
|
+
|
|
3
|
+
Powerhouse's published copy of the [Activepieces](https://www.activepieces.com)
|
|
4
|
+
piece framework, so a piece can be authored outside their monorepo.
|
|
5
|
+
|
|
6
|
+
It also adds `requireReactor`, which gives an action or trigger a
|
|
7
|
+
`ctx.reactor` for reading and writing Powerhouse documents. See
|
|
8
|
+
[Reactor access](#reactor-access-requirereactor-and-ctxreactor).
|
|
9
|
+
|
|
10
|
+
## Why this package exists
|
|
11
|
+
|
|
12
|
+
Activepieces pieces are written against `@activepieces/pieces-framework` and
|
|
13
|
+
`@activepieces/pieces-common`. Since Activepieces v0.86.0 most pieces ship as
|
|
14
|
+
self-contained bundles with the framework inlined, and upstream stopped
|
|
15
|
+
publishing those two packages to npm. Anyone authoring a piece outside the
|
|
16
|
+
Activepieces monorepo has nothing to install.
|
|
17
|
+
|
|
18
|
+
"Most", not all: their bundler externalises what esbuild cannot trace, so a
|
|
19
|
+
piece can still declare a dependency — 21 of the 760 published ones do. A
|
|
20
|
+
reactor installs those before loading the piece, with lifecycle scripts
|
|
21
|
+
disabled, which is why one needing a postinstall or a native build will not
|
|
22
|
+
run there whatever version is pinned.
|
|
23
|
+
|
|
24
|
+
This package vendors the framework, `pieces-common` and the two core packages
|
|
25
|
+
they depend on from a pinned upstream tag (see [UPSTREAM.md](./UPSTREAM.md)),
|
|
26
|
+
publishes them as ESM under the Powerhouse release train, and adds the
|
|
27
|
+
Powerhouse types on top. The authoring API is upstream's, unchanged.
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import {
|
|
31
|
+
createAction,
|
|
32
|
+
createPiece,
|
|
33
|
+
PieceAuth,
|
|
34
|
+
Property,
|
|
35
|
+
} from "@powerhousedao/pieces-framework";
|
|
36
|
+
import { httpClient, HttpMethod } from "@powerhousedao/pieces-framework/common";
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Writing a piece for a reactor package
|
|
40
|
+
|
|
41
|
+
1. **Start from a reactor package.** `ph init` gives you one; then add the
|
|
42
|
+
framework:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
pnpm add -D @powerhousedao/pieces-framework
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A dev dependency: `ph build` inlines the framework into each piece bundle.
|
|
49
|
+
The types need `@types/node`, which a `ph init` project already has.
|
|
50
|
+
|
|
51
|
+
2. **Write the piece** in `pieces/<name>/index.ts` with `createPiece`,
|
|
52
|
+
`createAction`, `createTrigger` and `Property`, exactly as an Activepieces
|
|
53
|
+
piece:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import {
|
|
57
|
+
createAction,
|
|
58
|
+
createPiece,
|
|
59
|
+
PieceAuth,
|
|
60
|
+
Property,
|
|
61
|
+
} from "@powerhousedao/pieces-framework";
|
|
62
|
+
|
|
63
|
+
const listInvoices = createAction({
|
|
64
|
+
auth: invoicesAuth,
|
|
65
|
+
name: "list_invoices",
|
|
66
|
+
displayName: "List invoices",
|
|
67
|
+
description: "Invoices in the billing system",
|
|
68
|
+
props: {
|
|
69
|
+
since: Property.ShortText({ displayName: "Since", required: false }),
|
|
70
|
+
},
|
|
71
|
+
async run(ctx) {
|
|
72
|
+
return clientFor(ctx.auth).listInvoices(ctx.propsValue.since);
|
|
73
|
+
},
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
export const invoices = createPiece({
|
|
77
|
+
displayName: "Invoices",
|
|
78
|
+
logoUrl: "https://example.com/invoices.png",
|
|
79
|
+
authors: ["acme"],
|
|
80
|
+
auth: invoicesAuth,
|
|
81
|
+
actions: [listInvoices],
|
|
82
|
+
triggers: [],
|
|
83
|
+
});
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
A piece usually connects a reactor to something outside it, and a workflow
|
|
87
|
+
composes it with the reactor piece's document steps. An action that needs
|
|
88
|
+
documents itself declares `requireReactor`, below.
|
|
89
|
+
|
|
90
|
+
To give a connection a status and an account label in Connect, declare
|
|
91
|
+
`validate` and `getConnectionIdentifier` on the auth. Both are handed the
|
|
92
|
+
flat auth value (here the props themselves, not `{ type, props }`):
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
const invoicesAuth = PieceAuth.CustomAuth({
|
|
96
|
+
displayName: "Invoices",
|
|
97
|
+
required: true,
|
|
98
|
+
props: {
|
|
99
|
+
base_url: Property.ShortText({
|
|
100
|
+
displayName: "Base URL",
|
|
101
|
+
required: true,
|
|
102
|
+
}),
|
|
103
|
+
token: PieceAuth.SecretText({ displayName: "Token", required: true }),
|
|
104
|
+
},
|
|
105
|
+
validate: async ({ auth }) => {
|
|
106
|
+
try {
|
|
107
|
+
await clientFor(auth).ping();
|
|
108
|
+
return { valid: true };
|
|
109
|
+
} catch (error) {
|
|
110
|
+
return { valid: false, error: String(error) };
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
getConnectionIdentifier: async ({ auth }) =>
|
|
114
|
+
(await clientFor(auth).me()).email,
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
A reactor runs `validate` for the check's result and, when it passes,
|
|
119
|
+
`getConnectionIdentifier` for the account label. The label is best-effort:
|
|
120
|
+
returning `undefined` or throwing keeps the previous label and still passes
|
|
121
|
+
the check.
|
|
122
|
+
|
|
123
|
+
3. **Register it.** List the piece in `pieces/index.ts` as a `PackagePiece`
|
|
124
|
+
and in the package manifest under `"pieces"`:
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
import type { PackagePiece } from "@powerhousedao/pieces-framework";
|
|
128
|
+
|
|
129
|
+
export const pieces: PackagePiece[] = [
|
|
130
|
+
{
|
|
131
|
+
name: "@acme/pieces-invoices",
|
|
132
|
+
entry: "dist/node/pieces/invoices/index.mjs",
|
|
133
|
+
},
|
|
134
|
+
];
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`entry` is the built module, relative to the package root: `ph build`
|
|
138
|
+
emits `pieces/<name>/index.ts` to `dist/node/pieces/<name>/index.mjs`.
|
|
139
|
+
|
|
140
|
+
4. **Build.** `ph build` bundles each `pieces/<name>/index.ts` on its own
|
|
141
|
+
into `dist/node/pieces/<name>/index.mjs`, with everything but node
|
|
142
|
+
built-ins inlined — the framework, its dependencies and the shared set that
|
|
143
|
+
document models and subgraphs leave to the host — because a host runs a
|
|
144
|
+
piece in a forked worker with no `node_modules` beside it. It then loads
|
|
145
|
+
each built piece once, in a child process, and writes two files next to it:
|
|
146
|
+
`descriptor.json`, the piece's own `metadata()` in the Activepieces
|
|
147
|
+
`PieceMetadata` shape (display name, logo, auth, every action and trigger
|
|
148
|
+
with its properties), and a `package.json` that makes the directory a
|
|
149
|
+
complete bundle. The `pieces` list in `dist/powerhouse.manifest.json` gets
|
|
150
|
+
each piece's version, description, `bundle` and `descriptor` paths, so a
|
|
151
|
+
registry can offer the piece before anyone installs the package. A piece's
|
|
152
|
+
version is always the package's own: the build writes it, and refuses a
|
|
153
|
+
list entry that declares one.
|
|
154
|
+
|
|
155
|
+
A package that ships only pieces is still an ordinary reactor package: it
|
|
156
|
+
carries the same boilerplate as any other, including a root `index.ts`,
|
|
157
|
+
`document-models/index.ts`, `editors/index.ts` and `style.css`, even when
|
|
158
|
+
those are empty. `ph build` runs every step for it unchanged, so there is
|
|
159
|
+
no piece-only mode to know about. The host that runs pieces on a reactor
|
|
160
|
+
(the workflow runtime) reads the `pieces` list and imports each `entry`.
|
|
161
|
+
|
|
162
|
+
Bundling with esbuild to ESM instead of `ph build`? `form-data`, which
|
|
163
|
+
`./common` uses, is CommonJS, so pass
|
|
164
|
+
`--banner:js="import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);"`
|
|
165
|
+
or the bundle throws `Dynamic require of "util" is not supported` on import.
|
|
166
|
+
|
|
167
|
+
## Reactor access: `requireReactor` and `ctx.reactor`
|
|
168
|
+
|
|
169
|
+
`createAction` and `createTrigger` from this package are upstream's, plus
|
|
170
|
+
`requireReactor: "read" | "write" | false`. The declaration types
|
|
171
|
+
`ctx.reactor` in every hook (`run` and `test`, and a trigger's other hooks):
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
import { createAction, Property } from "@powerhousedao/pieces-framework";
|
|
175
|
+
|
|
176
|
+
export const archiveInvoice = createAction({
|
|
177
|
+
name: "archive-invoice",
|
|
178
|
+
displayName: "Archive invoice",
|
|
179
|
+
description: "Sets an invoice's status to ARCHIVED",
|
|
180
|
+
requireAuth: false,
|
|
181
|
+
requireReactor: "write",
|
|
182
|
+
props: {
|
|
183
|
+
invoiceId: Property.ShortText({ displayName: "Invoice", required: true }),
|
|
184
|
+
},
|
|
185
|
+
async run(ctx) {
|
|
186
|
+
const doc = await ctx.reactor.get(ctx.propsValue.invoiceId);
|
|
187
|
+
const invoice = await ctx.reactor.getDocumentModelModuleForDocument(doc);
|
|
188
|
+
const handle = await ctx.reactor.write.execute(doc.header.id, "main", [
|
|
189
|
+
invoice.actions.setStatus({ status: "ARCHIVED" }),
|
|
190
|
+
]);
|
|
191
|
+
const { job } = await handle.readable;
|
|
192
|
+
if (job.result?.allApplied === false) throw new Error("Not archived");
|
|
193
|
+
const updated = await handle.document();
|
|
194
|
+
return { header: updated.header, state: updated.state };
|
|
195
|
+
},
|
|
196
|
+
});
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
- `"read"` types `ctx.reactor` as `ReactorReadClient`, `"write"` as
|
|
200
|
+
`ReactorClient`. Both are `Pick`s of `IReactorClient`, with the client's own
|
|
201
|
+
signatures; `ReadMethods`, `WriteMethods` and `RefusedMethods` name the
|
|
202
|
+
methods. `false`, like no declaration, gives no `ctx.reactor`.
|
|
203
|
+
- `ReactorClient.write` is `ReactorWriteClient`, a `Pick` of the reactor's
|
|
204
|
+
`IReactorWriteClient`: `create`, `createEmpty`, `execute`, `deleteDocument`
|
|
205
|
+
(no cascade), and `drives.addFile` and `drives.addFolder`
|
|
206
|
+
(`WriteHalfMethods`, `DriveWriteHalfMethods`). Each answers once its job is
|
|
207
|
+
accepted with a handle: `written`, `readable` (a receipt whose
|
|
208
|
+
`job.result.actions` holds each action's outcome) and `document(view?)`. A
|
|
209
|
+
reducer error is on the receipt, not thrown.
|
|
210
|
+
- The facade's writes (`create`, `createEmpty`, `execute`, `executeAsync`,
|
|
211
|
+
`deleteDocument`, `drives.addFile`, `drives.addFolder`) are deprecated and
|
|
212
|
+
still served, so published pieces keep working. They return once applied and
|
|
213
|
+
throw `ReactorActionsFailedError` on a reducer error.
|
|
214
|
+
- Build actions with the model's action creators, such as `setName` from
|
|
215
|
+
`@powerhousedao/shared/document-model`, `addFile` from
|
|
216
|
+
`@powerhousedao/shared/document-drive`, or `module.actions.*` from
|
|
217
|
+
`getDocumentModelModuleForDocument`, and pass them to `write.execute`. It
|
|
218
|
+
refuses document lifecycle actions, and the client's convenience writes
|
|
219
|
+
(`rename`, relationships, upgrades, batches, other drive writes) are refused,
|
|
220
|
+
on the facade and on `write`. Read a drive's nodes with `drives.listNodes`.
|
|
221
|
+
- A write the run user may not make throws `ReactorAccessDeniedError` before
|
|
222
|
+
anything is submitted. Its message ends with
|
|
223
|
+
`denied action indexes: [0,2]`; `deniedActionIndexes(error)` reads them.
|
|
224
|
+
- `query({ subgraph, query, variables })` (`IndexQueryMethods`, on both
|
|
225
|
+
types) reads a read-model index the host serves as a GraphQL subgraph, by
|
|
226
|
+
the name the host registers it under, with the host's own permission rules
|
|
227
|
+
applied for the run user. It answers `{ data, errors? }` and takes queries
|
|
228
|
+
only; a mutation is refused. A host that serves no indexes refuses the
|
|
229
|
+
method by name.
|
|
230
|
+
- The types come from `@powerhousedao/reactor` and `@powerhousedao/shared`,
|
|
231
|
+
which are optional, type-only peer dependencies. The build emits no import
|
|
232
|
+
of either.
|
|
233
|
+
- `ph build` copies the declaration into `descriptor.json`.
|
|
234
|
+
`ph generate piece-action` and `ph generate piece-trigger` write
|
|
235
|
+
`requireReactor: false`, or the value of `--require-reactor read|write`.
|
|
236
|
+
- `createAction` also takes `defaultTimeoutSeconds` (positive) and
|
|
237
|
+
`defaultRetry` (`maxAttempts`, plus optional `backoff`,
|
|
238
|
+
`initialDelaySeconds`, `maxDelaySeconds` and `retryOn`), used for a step
|
|
239
|
+
that sets no timeout or retry of its own. The workflow's own default retry
|
|
240
|
+
wins over the action's. A `defaultRetry` without delays
|
|
241
|
+
backs off exponentially from 5s, capped at 300s. `ph generate piece-action`
|
|
242
|
+
writes them commented out, or set from `--default-timeout-seconds` and
|
|
243
|
+
`--default-max-attempts`.
|
|
244
|
+
- The host serves `ctx.reactor`. Each call acts as the workflow's run user,
|
|
245
|
+
within the step's reactor connection and deadline. A handle waits only for
|
|
246
|
+
its own step's jobs; a failed job rejects its stages with `JobFailedError`.
|
|
247
|
+
- Errors cross the worker boundary by `name` and `message`, so compare
|
|
248
|
+
`error.name` against the exported constants: `ReactorAccessDeniedError`,
|
|
249
|
+
`ReactorJobFailedError`, `ReactorActionsFailedError`,
|
|
250
|
+
`ReactorJobPendingError`, `ReactorRequestClosedError` and
|
|
251
|
+
`DocumentModelUnavailableError`.
|
|
252
|
+
- `Property.Dropdown`, `Property.MultiSelectDropdown` and
|
|
253
|
+
`Property.DynamicProperties` type their resolver's `ctx.reactor` as
|
|
254
|
+
`ReactorReadClient | undefined`. A declared block's resolvers read as the
|
|
255
|
+
person using the editor and never write; the client is undefined when the
|
|
256
|
+
block declares nothing.
|
|
257
|
+
|
|
258
|
+
The academy page
|
|
259
|
+
[Reactor access from pieces](../../apps/academy/docs/academy/02-Learn/09-workflows/03-reactor-access.mdx)
|
|
260
|
+
covers the run-time rules, reactor connections and the run user.
|
|
261
|
+
|
|
262
|
+
## `./host`, for the host and not for piece authors
|
|
263
|
+
|
|
264
|
+
A host that _runs_ pieces needs more than the authoring API: stored prop values
|
|
265
|
+
arrive as strings from a form and have to be coerced to what the piece's
|
|
266
|
+
`props` declare, outbound requests have to be checked against the private
|
|
267
|
+
address space, and a thrown HTTP client error has to be turned into something a
|
|
268
|
+
user can read. Activepieces does all three in its engine; `./host` re-exports
|
|
269
|
+
that code so a Powerhouse host does not reimplement it.
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
import {
|
|
273
|
+
formatPieceError,
|
|
274
|
+
processors,
|
|
275
|
+
propsProcessor,
|
|
276
|
+
ssrfIpClassifier,
|
|
277
|
+
} from "@powerhousedao/pieces-framework/host";
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
From the engine, coercion of what an editor stored into what a piece's `props`
|
|
281
|
+
declare:
|
|
282
|
+
|
|
283
|
+
- `processors` — `PropertyType` → coercion function, for the eleven types that
|
|
284
|
+
need one, and `numberProcessor`, `checkboxProcessor`, `dateTimeProcessor`,
|
|
285
|
+
`fileProcessor`, `jsonProcessor`, `objectProcessor`, `textProcessor` and
|
|
286
|
+
`multiSelectProcessor` individually.
|
|
287
|
+
- `arrayZipperProcessor` — turns an object of parallel arrays into `ARRAY`
|
|
288
|
+
items; `ARRAY` has no entry in the map.
|
|
289
|
+
- `propsProcessor.applyProcessorsAndValidators` — a whole props map at once,
|
|
290
|
+
auth and nested `ARRAY`/`DYNAMIC` props included, returning the processed
|
|
291
|
+
input and per-key validation errors.
|
|
292
|
+
- `dynamicPropKeys` — escapes and restores `DYNAMIC` prop keys around a form
|
|
293
|
+
that treats `.` and `[` as path separators.
|
|
294
|
+
- `ProcessorFn`, and `PropertySettings` (ours, see
|
|
295
|
+
[UPSTREAM.md](./UPSTREAM.md)) for the stored `DYNAMIC` schema.
|
|
296
|
+
|
|
297
|
+
From `core-utils`, the two host jobs that are not coercion:
|
|
298
|
+
|
|
299
|
+
- `ssrfIpClassifier.isBlockedIp({ ip, allowList })` — blocks every non-unicast
|
|
300
|
+
range, with CIDR entries in the allow list.
|
|
301
|
+
- `formatPieceError` — lifts the API message out of an HTTP-shaped error,
|
|
302
|
+
strips an HTML error page down to its text and caps serialization depth;
|
|
303
|
+
with `tryParseFriendlyPieceError` and the `FriendlyPieceError` type.
|
|
304
|
+
|
|
305
|
+
Nothing here belongs in a piece: a piece is handed values that are already
|
|
306
|
+
coerced. `.` and `./common` are unchanged, and `test/surface.test.ts` holds them
|
|
307
|
+
that way.
|
|
308
|
+
|
|
309
|
+
The consumer is [`@powerhousedao/reactor-workflow`](../reactor-workflow), which
|
|
310
|
+
runs pieces on a reactor: its `context/normalize.ts` dispatches to `processors`,
|
|
311
|
+
its `worker/egress.ts` classifies with `ssrfIpClassifier`, and its worker runs a
|
|
312
|
+
thrown piece error through `formatPieceError` before redacting it.
|
|
313
|
+
|
|
314
|
+
The coercion half comes from `@activepieces/engine`, of which this package
|
|
315
|
+
vendors only the prop-coercion files, for the reasons in
|
|
316
|
+
[UPSTREAM.md](./UPSTREAM.md). `dayjs` (the DATE_TIME processor) and `ipaddr.js`
|
|
317
|
+
(the classifier) are runtime dependencies because `./host` reaches them.
|
|
318
|
+
|
|
319
|
+
## `./block-type`, block identity and versions
|
|
320
|
+
|
|
321
|
+
A workflow names a block the way Activepieces does, with three fields:
|
|
322
|
+
`pieceName`, `pieceVersion` and `actionName` for a step, or `triggerName` for a
|
|
323
|
+
trigger. The engine's own blocks are a piece too, `@powerhousedao/piece-core`
|
|
324
|
+
(`CORE_PIECE_NAME` in `./workflow`). This module has no dependencies and is safe
|
|
325
|
+
in the browser, so the editor and the runtime share it.
|
|
326
|
+
|
|
327
|
+
A piece's version is the version of its package. The version is exact semver
|
|
328
|
+
2.0: prereleases and build metadata are allowed, ranges and dist-tags are not.
|
|
329
|
+
|
|
330
|
+
- `isExactVersion(v)` says whether a version can be pinned.
|
|
331
|
+
- `blockKey({ pieceName, kind, name })` is the version-free identity as one
|
|
332
|
+
string, for map and cache keys.
|
|
333
|
+
- `compareVersions(a, b)` orders by semver precedence.
|
|
334
|
+
- `pickClosestVersion(requested, available)` returns `{ version, match }`,
|
|
335
|
+
picking the first rule that matches:
|
|
336
|
+
1. The exact version (`exact`).
|
|
337
|
+
2. The highest same-major version at or above the request (`compatible`).
|
|
338
|
+
3. The highest same-major version below the request (`fallback`).
|
|
339
|
+
4. The highest version of any major (`fallback`).
|
|
340
|
+
|
|
341
|
+
For `0.x`, same major means same minor.
|
|
342
|
+
|
|
343
|
+
## Publishing the same piece to Activepieces
|
|
344
|
+
|
|
345
|
+
A piece written against this package is a plain Activepieces piece. To
|
|
346
|
+
contribute it upstream, scaffold one in the Activepieces monorepo with
|
|
347
|
+
`npm run cli pieces create`, copy your `src/` over its own, rewrite the import
|
|
348
|
+
specifiers (`@powerhousedao/pieces-framework` to
|
|
349
|
+
`@activepieces/pieces-framework`, `@powerhousedao/pieces-framework/common` to
|
|
350
|
+
`@activepieces/pieces-common`) and run `npm run build-piece <name>`.
|
|
351
|
+
|
|
352
|
+
## Syncing upstream
|
|
353
|
+
|
|
354
|
+
```sh
|
|
355
|
+
pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag d078d47750b53c13b837b2bec86b0402b4bff94f
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
`scripts/sync-upstream.mts` is the only thing that writes `upstream/` and
|
|
359
|
+
`test/upstream/`. It fetches the tag, copies the four piece source trees plus a
|
|
360
|
+
named handful of engine files, rewrites
|
|
361
|
+
them to ESM with `.js` specifiers and type-only imports, formats them, applies
|
|
362
|
+
a short list of literal patches that fail loudly when upstream changes, and
|
|
363
|
+
records every file's upstream path and hash in `upstream/MANIFEST.json`.
|
|
364
|
+
Details in [UPSTREAM.md](./UPSTREAM.md).
|
|
365
|
+
|
|
366
|
+
## License
|
|
367
|
+
|
|
368
|
+
MIT. The vendored Activepieces code keeps its original MIT license and
|
|
369
|
+
copyright, reproduced verbatim in [LICENSE](./LICENSE) alongside the Powerhouse
|
|
370
|
+
notice for everything else. The framework is inlined into every piece an
|
|
371
|
+
external developer builds, which is why this package is MIT rather than AGPL
|
|
372
|
+
like the rest of the Powerhouse monorepo.
|
package/UPSTREAM.md
ADDED
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
# Upstream
|
|
2
|
+
|
|
3
|
+
`upstream/` and `test/upstream/` are generated from
|
|
4
|
+
[activepieces/activepieces](https://github.com/activepieces/activepieces).
|
|
5
|
+
Never edit them by hand; re-run the sync instead.
|
|
6
|
+
|
|
7
|
+
| | |
|
|
8
|
+
| --------- | ------------------------------------------ |
|
|
9
|
+
| Tag | none (`main`) |
|
|
10
|
+
| Commit | `d078d47750b53c13b837b2bec86b0402b4bff94f` |
|
|
11
|
+
| Committed | 2026-10-30 |
|
|
12
|
+
|
|
13
|
+
The same facts, plus the per-file upstream path and the SHA-256 of every
|
|
14
|
+
original file, live in `upstream/MANIFEST.json`; the package versions are in
|
|
15
|
+
`package.json` under `"upstream"`.
|
|
16
|
+
|
|
17
|
+
## What is vendored
|
|
18
|
+
|
|
19
|
+
| Upstream package | Upstream path | Here |
|
|
20
|
+
| --------------------------------------- | ------------------------------- | ---------------------------- |
|
|
21
|
+
| `@activepieces/pieces-framework` 0.42.0 | `packages/pieces/framework/src` | `upstream/framework/` |
|
|
22
|
+
| `@activepieces/pieces-common` 0.15.1 | `packages/pieces/common/src` | `upstream/common/` |
|
|
23
|
+
| `@activepieces/core-piece-types` 0.12.3 | `packages/core/piece-types/src` | `upstream/core-piece-types/` |
|
|
24
|
+
| `@activepieces/core-utils` 0.11.0 | `packages/core/utils/src` | `upstream/core-utils/` |
|
|
25
|
+
| `@activepieces/engine` 0.7.0 | `packages/server/engine/src` | `upstream/engine/` |
|
|
26
|
+
|
|
27
|
+
The first four are vendored whole. The engine is not: `PACKAGES` gives it an
|
|
28
|
+
explicit `files` list, and the sync fails if any listed path disappears
|
|
29
|
+
upstream. Only the prop-coercion corner is taken — `lib/variables/processors/*`,
|
|
30
|
+
`lib/variables/props-processor.ts` and `lib/helper/dynamic-prop-keys.ts` — which
|
|
31
|
+
is what `./host` re-exports. Everything else in that package reaches for the
|
|
32
|
+
flow executor, the isolated-vm sandbox or the platform API: the trigger helper,
|
|
33
|
+
the piece executor and loader, and `lib/helper/error-handling.ts`, whose
|
|
34
|
+
retry/continue-on-failure logic takes `EngineConstants` and
|
|
35
|
+
`FlowExecutorContext` and so would drag the whole handler tree in.
|
|
36
|
+
`lib/variables/property-path.ts` is left out too: `props-processor.ts` does not
|
|
37
|
+
import it, and it would add a `jsep` dependency.
|
|
38
|
+
|
|
39
|
+
Each package's own vitest suites (`*.spec.ts`, `*.test.ts` under `src/`, and
|
|
40
|
+
`test/`) go to `test/upstream/<package>/` and run with `pnpm test`.
|
|
41
|
+
|
|
42
|
+
Left out: `mime-db-min.cjs` (upstream's bundler alias that keeps `mime-db`,
|
|
43
|
+
pulled in through `form-data`, out of piece bundles; aliasing is the piece
|
|
44
|
+
build's job, so `ph build` may adopt it later) and upstream's unused `ai` and
|
|
45
|
+
`semver` dependencies.
|
|
46
|
+
Of the engine's own tests only those that exercise vendored code come along:
|
|
47
|
+
`test/variables/{props-validator,file-processor,dynamic-prop-keys}.test.ts`,
|
|
48
|
+
`test/helper/polling-helper.test.ts` and
|
|
49
|
+
`test/http/formdata-multipart-claim-verify.test.ts` (which guards the patched
|
|
50
|
+
`fetch-http-client.ts`). The rest need `@activepieces/shared`,
|
|
51
|
+
`props-resolver` or `FlowExecutorContext`.
|
|
52
|
+
|
|
53
|
+
`@activepieces/shared` (8k lines of platform entities) is not vendored. The four
|
|
54
|
+
piece packages never import it; the engine files do, so the codemod re-homes
|
|
55
|
+
each symbol they use — `AUTHENTICATION_PROPERTY_NAME` and `AppConnectionValue`
|
|
56
|
+
to `upstream/core-piece-types/`, which really defines them, and `PropertySettings`
|
|
57
|
+
and `PropertyExecutionType` to `src/host/shared-shim.ts`, a Powerhouse-owned
|
|
58
|
+
declaration of the minimal shapes `props-processor.ts` and its tests read. An
|
|
59
|
+
unmapped symbol fails the sync.
|
|
60
|
+
|
|
61
|
+
`deepmerge-ts` is a devDependency only: `core-utils` imports it in
|
|
62
|
+
`deepMergeAndCast`, which the framework barrel never re-exports, so the source
|
|
63
|
+
typechecks against it and the build tree-shakes it away. `test/dist.test.ts`
|
|
64
|
+
fails if a sync makes it reachable; that is the moment to move it to
|
|
65
|
+
`dependencies`. `ipaddr.js` and `dayjs` are runtime dependencies because `./host`
|
|
66
|
+
does reach them, through `ssrfIpClassifier` and the DATE_TIME processor.
|
|
67
|
+
|
|
68
|
+
## How to sync
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag <tag or commit SHA>
|
|
72
|
+
# or, from a checkout you already have at that tag or commit:
|
|
73
|
+
pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag <tag> --from ../activepieces
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Without `--from` the script sparse-clones the tag (or fetches the commit) into a temp dir. Then run the
|
|
77
|
+
gates (`tsc`, `lint`, `test`, `build`) and commit the result together with the
|
|
78
|
+
`UPSTREAM.md` table above. The script is idempotent: running it twice yields no
|
|
79
|
+
diff.
|
|
80
|
+
|
|
81
|
+
## What the codemod changes
|
|
82
|
+
|
|
83
|
+
Upstream is CommonJS with extensionless imports; this package is ESM under
|
|
84
|
+
`NodeNext` with `verbatimModuleSyntax`. For every copied `.ts` file the script:
|
|
85
|
+
|
|
86
|
+
1. Rewrites bare `@activepieces/{pieces-framework,pieces-common,core-piece-types,core-utils}`
|
|
87
|
+
imports to relative paths into `upstream/`.
|
|
88
|
+
2. Adds `.js` (or `/index.js`) to relative specifiers, resolved against the
|
|
89
|
+
real files.
|
|
90
|
+
3. Prefixes node builtins with `node:`, and adds the extension Node's ESM
|
|
91
|
+
resolver will not infer for a subpath of a dependency with no `"exports"`
|
|
92
|
+
map (`dayjs/plugin/utc` becomes `dayjs/plugin/utc.js`).
|
|
93
|
+
4. Prepends a two-line header naming the upstream path and the tag.
|
|
94
|
+
5. Marks type-only imports and re-exports with ts-morph
|
|
95
|
+
(`scripts/sync-upstream-type-only.mts`, a port of typescript-eslint's
|
|
96
|
+
`consistent-type-imports` and `consistent-type-exports` fixes) so they
|
|
97
|
+
satisfy `verbatimModuleSyntax` and `isolatedModules`, then formats the tree
|
|
98
|
+
with the repo's prettier config.
|
|
99
|
+
6. Splits an `@activepieces/shared` import across the modules that really own
|
|
100
|
+
each symbol, per `SHARED_SYMBOL_HOMES`.
|
|
101
|
+
7. Applies the literal patches listed in `PATCHES` in
|
|
102
|
+
`scripts/sync-upstream.mts`. Each must match exactly the expected number of
|
|
103
|
+
times or the sync fails, so a change upstream cannot go unnoticed.
|
|
104
|
+
|
|
105
|
+
Current patches:
|
|
106
|
+
|
|
107
|
+
- `upstream/common/lib/http/core/fetch-http-client.ts`: cast a buffered
|
|
108
|
+
form-data body to `BodyInit` (`@types/node` 25 no longer accepts
|
|
109
|
+
`Buffer<ArrayBufferLike>` there), and replace a `@ts-expect-error` whose
|
|
110
|
+
target line prettier moves with an explicit cast on `Readable.fromWeb`.
|
|
111
|
+
- `upstream/common/lib/http/core/fetch-http-client.ts`: drop the unconditional
|
|
112
|
+
`process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"` at the top of `sendRequest`.
|
|
113
|
+
That flag is process-wide, so it disabled certificate verification for every
|
|
114
|
+
HTTPS request in the host for as long as the process ran, not just the
|
|
115
|
+
current one. Upstream's own bug (activepieces/activepieces@main still has
|
|
116
|
+
it); no design here relies on it.
|
|
117
|
+
- `upstream/common/lib/http/core/fetch-http-client.ts`: stop `console.error`-ing
|
|
118
|
+
the `HttpError` built for a failed request. `HttpError`'s message embeds the
|
|
119
|
+
raw outgoing request body, so this was writing piece secrets (API keys,
|
|
120
|
+
tokens, form fields) to host-level logs on every failed call. Upstream's own
|
|
121
|
+
bug too; callers already get the same detail back via `toFailsafeOutput`.
|
|
122
|
+
- `upstream/common/lib/stream/index.ts`: guard `readChunks` against a
|
|
123
|
+
non-positive `chunkSize`. `pendingLength >= chunkSize` is permanently true
|
|
124
|
+
for `chunkSize <= 0`, so the drain loop never yields control back to the
|
|
125
|
+
outer `for await`, hanging the generator forever. Unreachable today (nothing
|
|
126
|
+
calls it yet) but it is public framework API.
|
|
127
|
+
- `upstream/common/lib/helpers/index.ts`: in `createCustomApiCallAction`, stop
|
|
128
|
+
injecting `authValue` into headers whenever `authLocation` is merely
|
|
129
|
+
non-nil. `authLocation` defaults to `"headers"` and is never actually nil at
|
|
130
|
+
that point, so `authLocation === "headers" || !isNil(authLocation)` always
|
|
131
|
+
held — query-param credentials were duplicated into the request headers.
|
|
132
|
+
- `upstream/framework/lib/property/input/array-property.ts`: add
|
|
133
|
+
`JsonProperty` and `ColorProperty` to the runtime `ArraySubProps` union (and
|
|
134
|
+
import them as values). The exported `ArraySubProps<R>` type and
|
|
135
|
+
`Property.Array` both already allow Json/Color sub-properties; the runtime
|
|
136
|
+
schema rejected them.
|
|
137
|
+
- `upstream/framework/lib/property/input/array-property.ts`: make
|
|
138
|
+
`ArrayProperty`'s `properties` field `z.optional(...)`. The exported
|
|
139
|
+
`ArrayProperty<R>` type already marks it optional, and
|
|
140
|
+
`piecePropertiesUtils.buildSchema` already handles an absent value; the
|
|
141
|
+
runtime schema required it.
|
|
142
|
+
- `upstream/framework/lib/property/input/index.ts`: add `CustomProperty` to
|
|
143
|
+
the runtime `InputProperty` union (and import it as a value).
|
|
144
|
+
`Property.Custom` builds exactly that shape, and it's part of the exported
|
|
145
|
+
`InputProperty` type, but the runtime schema rejected it.
|
|
146
|
+
- `upstream/framework/lib/property/authentication/custom-auth-prop.ts`: add
|
|
147
|
+
`SecretTextProperty`, `MarkDownProperty` and `StaticMultiSelectDropdownProperty`
|
|
148
|
+
to the runtime `CustomAuthProps` union (and import them as values). All
|
|
149
|
+
three are part of the exported `CustomAuthProps` type; the runtime schema
|
|
150
|
+
was narrower.
|
|
151
|
+
- `upstream/framework/lib/property/input/markdown-property.ts`: add an
|
|
152
|
+
optional `variant` field to the runtime `MarkDownProperty` schema.
|
|
153
|
+
`Property.MarkDown` always writes one and the exported type declares it,
|
|
154
|
+
but the schema had no such key, so zod silently stripped
|
|
155
|
+
`WARNING`/`TIP`/`BORDERLESS` variants on parse.
|
|
156
|
+
- `upstream/framework/lib/property/input/file-property.ts`: add an optional
|
|
157
|
+
`path` to `ApStreamingFile`, the absolute path of a streaming FILE staged on
|
|
158
|
+
local disk. reactor-workflow sets it so a piece can read the file in place
|
|
159
|
+
(DuckDB, for one) instead of copying the body out first.
|
|
160
|
+
- `upstream/framework/lib/trigger/trigger.ts`: give `createTrigger`'s switch a
|
|
161
|
+
`default` that throws, naming the trigger and its `type`. The switch had none,
|
|
162
|
+
so a missing or misspelt strategy returned `undefined`, and the piece failed
|
|
163
|
+
later wherever that trigger was first read. TypeScript already rejects it;
|
|
164
|
+
this covers code that bypasses the types.
|
|
165
|
+
- `upstream/framework/index.ts` and `upstream/framework/lib/property/index.ts`:
|
|
166
|
+
re-export `SeekPage`, `McpAuthConfig` and `InputProperty` as values instead
|
|
167
|
+
of `export type`. Each is a zod schema merged with a type; rolldown-plugin-dts
|
|
168
|
+
drops the `type` modifier when it bundles `dist/index.d.ts`, so upstream's
|
|
169
|
+
type-only re-export let `import { SeekPage }` typecheck and then fail at link
|
|
170
|
+
time. The runtime gains three exports upstream's lacks; `test/dist.test.ts`
|
|
171
|
+
holds the d.ts to the runtime.
|
|
172
|
+
- `upstream/engine/lib/variables/props-processor.ts`: export
|
|
173
|
+
`validateProperty`, the validator half of `applyProcessorsAndValidators`.
|
|
174
|
+
A host that coerces values with its own processors first (reactor-workflow
|
|
175
|
+
hydrates FILE props itself) validates the result with it.
|
|
176
|
+
- `test/upstream/framework/test/connection-identifier-flag.test.ts`: pass
|
|
177
|
+
`authors: []` to `createPiece` (upstream does not typecheck its tests).
|
|
178
|
+
- `test/upstream/engine/test/variables/dynamic-prop-keys.test.ts`: pass
|
|
179
|
+
`auth: undefined` to `Property.DynamicProperties`, which requires it.
|
|
180
|
+
- `test/upstream/core-utils/test/ai-provider-health.test.ts`: make the outcome
|
|
181
|
+
reporter return `void` instead of `Array.prototype.push`'s number (three
|
|
182
|
+
sites).
|
|
183
|
+
- `test/upstream/engine/test/variables/file-processor.test.ts`: cast the
|
|
184
|
+
processor's `unknown` result to `ApStreamingFile` instead of annotating the
|
|
185
|
+
binding (five sites).
|
|
186
|
+
- `test/upstream/engine/test/variables/props-validator.test.ts`: pass
|
|
187
|
+
`auth: undefined` to `Property.Dropdown` and `Property.MultiSelectDropdown`,
|
|
188
|
+
which require it.
|
|
189
|
+
|
|
190
|
+
The vendored trees are excluded from the root ESLint run: their lint stance is
|
|
191
|
+
upstream's, and the codemod already applies this repo's formatting.
|
|
192
|
+
|
|
193
|
+
## Conformance suite for reactor-workflow
|
|
194
|
+
|
|
195
|
+
The same sync also generates
|
|
196
|
+
[`../reactor-workflow/test/upstream/`](../reactor-workflow/test/upstream):
|
|
197
|
+
Activepieces engine tests that run against our engine instead of vendored code.
|
|
198
|
+
It lives in this script rather than a second one so that one run, from one
|
|
199
|
+
checkout, regenerates both trees under one codemod and one patch contract.
|
|
200
|
+
|
|
201
|
+
`CONFORMANCE` in `scripts/sync-upstream.mts` lists each upstream test and its
|
|
202
|
+
target, optionally cut down to literal `excerpt` segments. For each file the
|
|
203
|
+
sync:
|
|
204
|
+
|
|
205
|
+
1. Rewrites `@activepieces/pieces-framework` and `@activepieces/pieces-common`
|
|
206
|
+
to our published `@powerhousedao/pieces-framework` entries.
|
|
207
|
+
2. Rewrites every other upstream import through `IMPORT_REDIRECTS` to an adapter
|
|
208
|
+
in `../reactor-workflow/test/upstream-adapters/`, which exposes the upstream
|
|
209
|
+
API (`createContextStore`, `createConnectionResolver`, `ssrfGuard`,
|
|
210
|
+
`propsProcessor`, the `@activepieces/shared` symbols) over our code. An
|
|
211
|
+
import with no redirect fails the sync.
|
|
212
|
+
3. Adds the header, formats, and applies `CONFORMANCE_PATCHES`, which carry the
|
|
213
|
+
same `count` and `why` as `PATCHES`.
|
|
214
|
+
4. Marks each `CONFORMANCE_SKIPS` case `it.skip` and each `KNOWN_DIVERGENCES`
|
|
215
|
+
case `it.fails`, with a comment giving the reason and, for a divergence, the
|
|
216
|
+
issue or README item that fixes it; a deliberate divergence names none. A
|
|
217
|
+
name that no longer matches upstream fails the sync. When a fix lands, its
|
|
218
|
+
`it.fails` starts failing: drop the entry and re-sync.
|
|
219
|
+
5. Writes `test/upstream/MANIFEST.json` there, with the upstream path and
|
|
220
|
+
SHA-256 of each original and the lists of divergences and skips.
|
|
221
|
+
|
|
222
|
+
Nothing is taken from `packages/ee/` or `packages/server/api/src/app/ee`, which
|
|
223
|
+
are not MIT.
|