@dx-dz/plugin-sdk
The stable, minimal public API a standalone dx-dz plugin builds against — a
curated re-export of the operator-authoring surface from @dxdz/model
(ADR-0001).
Published to npm as
@dx-dz/plugin-sdk(thedx-dzorg). Internal workspace packages keep the@dxdz/*scope — they are private and never published, so only this one matches the npm org.
@dxdz/model stays the single source of truth; this package is a bundled view
of it. Plugins bundle with no externals, so the SDK is needed only at
build + typecheck time — never at plugin runtime.
Public API
| Group | Exports |
|---|---|
| Operator authoring | OperatorBehavior, OperatorDef, OperatorDefAny, OperatorCategory, OperatorDisplay, OperatorOutputPort, OperatorExecuteResult, OperatorRef(+Schema) |
| Config form | FormDef, FormSection, FormField, FormWidget, WidgetOptions, ShowWhenRule; builders eq/neq/inSet/notIn/andOf/orOf/notOf/evaluateShowWhen |
| Runtime ctx | Ctx, TriggerCtx, CtxMeta, Logger, LogLevel, SecretsAccessor, RunScratch, HttpFetcher, ExpressionEngine, ExpressionContext, PageContext, TimeoutPolicy(+DEFAULT_TIMEOUT_POLICY), MetricAttrs, MetricsEmitter(+NOOP_METRICS), OidcClientCredentialsRequest, OidcTokenAccessor, TriggerHealth |
| Error contract | OperationError(+Schema), RunnerErrorCode(+RUNNER_ERROR_CODES) |
| Plugin tooling | PluginManifest*(+schemas), PluginPayload(+schema); computeIntegrity/verifyIntegrity/integrityEquals/isIntegrityHash/SHA256_INTEGRITY_PATTERN; LockFile*(+schemas)/sortLockfileEntries/LOCK_FILE_NAME |
Deliberately not exported: flow / analyzer / deployment / run-event / observability / operator-card / expression-catalog / secret-ref. See ADR-0001 for the full in/out rationale.
Authoring an operator
import { type OperatorBehavior, type Ctx, eq } from '@dx-dz/plugin-sdk';
import { z } from 'zod';
export const myOperator: OperatorBehavior<{ url: string }> = {
pluginName: '@acme/my-plugin',
operatorId: 'fetch',
category: 'step',
display: { displayName: 'Fetch', description: '…', family: 'Acme', icon: 'bolt' },
configSchema: z.object({ url: z.string() }),
configForm: { sections: [{ id: 'main', title: 'Main', fields: [{ key: 'url', label: 'URL', widget: 'text' }] }] },
outputs: [{ name: 'out' }, { name: 'error' }],
async execute(ctx: Ctx, _input, config) {
const res = await ctx.http.fetch(config.url, { signal: ctx.signal });
return { port: 'out', data: await res.json() };
},
};Build
nx build @dx-dz/plugin-sdk runs tsup, which inlines @dxdz/model into
both the emitted JS and the rolled-up .d.ts (noExternal) — the published
tarball carries no dependency on the private model package. zod + tslib stay
external. typecheck (tsc, no emit) validates types; test (vitest) guards the
surface against ADR-0001.
Status
- #423: the carve — the curated re-export surface + build/typecheck/test.
- #424 (this): the publishable, self-contained bundle (tsup dts/js rollup)
- publish config. First release published manually as
0.0.1; subsequent0.0.xpublish from CI via npm OIDC Trusted Publishing.
- publish config. First release published manually as