@alneas/eaos-plugin-approval API

@alneas/eaos-plugin-approval API

Public entrypoints

Import	Contract
@alneas/eaos-plugin-approval/lifecycle	Typed public export
@alneas/eaos-plugin-approval/react	Typed public export
@alneas/eaos-plugin-approval/workspace	Typed public export
@alneas/eaos-plugin-approval/rules	Typed public export
@alneas/eaos-plugin-approval/user-help	Typed public export
@alneas/eaos-plugin-approval	Typed public export
@alneas/eaos-plugin-approval/service	Typed public export
@alneas/eaos-plugin-approval/manifest	Typed public export
@alneas/eaos-plugin-approval/runtime	Typed public export
@alneas/eaos-plugin-approval/user-guide.json	Packaged JSON contract/data asset; resolve this exported path with the host loader
@alneas/eaos-plugin-approval/deployment.json	Packaged JSON contract/data asset; resolve this exported path with the host loader

[FUNCTION] ApprovalDecisionForm

Renders a schema-driven plugin command form backed by a host callback.

Imports: @alneas/eaos-plugin-approval/react.

Signature

declare function ApprovalDecisionForm({ decide, labels }: {
    decide(values: {
        action: 'approve' | 'reject';
        comment?: string;
    }): Promise<void>;
    labels: {
        action: string;
        comment: string;
    };
}): React.JSX.Element;

Parameters

Name	Type	Required	Description
{ decide, labels }	{ decide(values: { action: 'approve' | 'reject'; comment?: string; }): Promise<void>; labels: { action: string; comment: string; }; }	Yes	decide is an authenticated async host command and labels supplies field captions. Decision values contain required action approve/reject and optional comment; host closes over request ID and revision.

Returns

React.JSX.Element

A plugin help panel and react-tools FormView in create mode.

Remarks

Requires React,

Public members

argument1.decide

Authenticated host decision callback; closes over current request ID and revision and resolves on completion.

Parameters:

• values: Approve/reject action and optional comment; the host closes over the current authorized request ID/revision.

Returns: Resolves without a value when the host command completes; the form handles its Promise outcome.

Errors and rejections

Rejects host authorization, validation, transport or persistence failures; reload current state after uncertain write outcomes.

Example:

import { ApprovalDecisionForm } from '@alneas/eaos-plugin-approval/react';
type HostCommand = Parameters<typeof ApprovalDecisionForm>[0]['decide'];
export async function runHostCommand(command: HostCommand, values: Parameters<HostCommand>[0]) {
 await command(values);
}

argument1.decide.values.action

Approved action discriminator: approve or reject.

argument1.decide.values.comment

Optional decision comment.

argument1.labels

Plugin field captions rendered by the command form.

argument1.labels.action

Approved action discriminator: approve or reject.

argument1.labels.comment

Optional decision comment.

Example

import * as React from 'react';
import { ApprovalDecisionForm } from '@alneas/eaos-plugin-approval/react';
export function Form({ decide }: Pick<React.ComponentProps<typeof ApprovalDecisionForm>, 'decide'>) { return <ApprovalDecisionForm decide={decide} labels={{ action: 'Decision', comment: 'Comment' }}/>; }

[INTERFACE] ApprovalDecisionReceipt

Final approval/rejection evidence identifying actor, stage and resulting revision.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/service.

Signature

interface ApprovalDecisionReceipt {
    receiptId: string;
    approvalId: string;
    tenantId: string;
    decision: 'approved' | 'rejected';
    actorId: string;
    actorRoles: string[];
    stageId: string;
    decidedAt: string;
    revision: number;
    bindingHash?: string;
    comment?: string;
}

Parameters

Name	Type	Required	Description
receiptId	string	Yes	Generated final-decision receipt identifier.
approvalId	string	Yes	Persisted approval request identifier.
tenantId	string	Yes	Tenant owning the decision.
decision	'approved' | 'rejected'	Yes	Final approved or rejected outcome; intermediate approvals have no receipt.
actorId	string	Yes	Authenticated deciding user.
actorRoles	string[]	Yes	Copied verified roles at decision time.
stageId	string	Yes	Stage producing the final outcome.
decidedAt	string	Yes	Parseable decision timestamp, generated as ISO UTC by the service.
revision	number	Yes	Positive resulting request revision.
bindingHash	string	No	Optional approved action binding hash copied from the bound request.
comment	string	No	Optional nonblank final comment, up to 4000 characters.

Returns

Type declaration; no runtime value.

See also

ApprovalService for a complete host integration example.

Public members

receiptId

Generated final-decision receipt identifier.

approvalId

Persisted approval request identifier.

tenantId

Tenant owning the decision.

decision

Final approved or rejected outcome; intermediate approvals have no receipt.

actorId

Authenticated deciding user.

actorRoles

Copied verified roles at decision time.

stageId

Stage producing the final outcome.

decidedAt

Parseable decision timestamp, generated as ISO UTC by the service.

revision

Positive resulting request revision.

bindingHash

Optional approved action binding hash copied from the bound request.

comment

Optional nonblank final comment, up to 4000 characters.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] ApprovalDocument

Persisted approval state, stage assignments and append-only decision history.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/service.

Signature

interface ApprovalDocument {
    templateId: string;
    title: string;
    targetType: string;
    targetId: string;
    requestedBy: string;
    stages: ApprovalStage[];
    allowSelfApproval: boolean;
    currentStage: number;
    binding?: ApprovalBinding;
    status: 'pending' | 'approved' | 'rejected' | 'withdrawn';
    decisionReceipt?: ApprovalDecisionReceipt;
    history: {
        action: 'submitted' | 'approved' | 'rejected' | 'withdrawn';
        actorId: string;
        stageId?: string;
        comment?: string;
        at: string;
    }[];
}

Parameters

Name	Type	Required	Description
templateId	string	Yes	Host template selected at submission.
title	string	Yes	Nonblank request title, at most 1000 characters.
targetType	string	Yes	Host resource type being reviewed.
targetId	string	Yes	Host resource identifier being reviewed.
requestedBy	string	Yes	Authenticated original requester user ID.
stages	ApprovalStage[]	Yes	Copied stage assignments, unaffected by later template edits.
allowSelfApproval	boolean	Yes	Stored permission for requester approval, default false at submission.
currentStage	number	Yes	Zero-based current stage; equals stages.length after final approval.
binding	ApprovalBinding	No	Optional host-verified action/proposal binding.
status	'pending' | 'approved' | 'rejected' | 'withdrawn'	Yes	Pending, final approved/rejected, or requester-withdrawn state.
decisionReceipt	ApprovalDecisionReceipt	No	Final approved/rejected evidence; absent for pending and withdrawn requests.
history	{ action: 'submitted' | 'approved' | 'rejected' | 'withdrawn'; actorId: string; stageId?: string; comment?: string; at: string; }[]	Yes	Ordered submitted/approved/rejected/withdrawn entries with actor/time and optional stage/comment.

Returns

Type declaration; no runtime value.

See also

ApprovalService for a complete host integration example.

Public members

templateId

Host template selected at submission.

title

Nonblank request title, at most 1000 characters.

targetType

Host resource type being reviewed.

targetId

Host resource identifier being reviewed.

requestedBy

Authenticated original requester user ID.

stages

Copied stage assignments, unaffected by later template edits.

allowSelfApproval

Stored permission for requester approval, default false at submission.

currentStage

Zero-based current stage; equals stages.length after final approval.

binding

Optional host-verified action/proposal binding.

status

Pending, final approved/rejected, or requester-withdrawn state.

decisionReceipt

Final approved/rejected evidence; absent for pending and withdrawn requests.

history

Ordered submitted/approved/rejected/withdrawn entries with actor/time and optional stage/comment.

history[].action

History transition: submitted, approved, rejected or withdrawn.

history[].actorId

Authenticated user who performed this transition.

history[].stageId

Stage acted upon; absent on submission/withdrawal.

history[].comment

Optional decision comment.

history[].at

ISO UTC transition timestamp.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] ApprovalList

Approval records exposed by the host workspace loader.

Imports: @alneas/eaos-plugin-approval/react, @alneas/eaos-plugin-approval/workspace.

Signature

interface ApprovalList {
    requests: {
        id: string;
        revision: number;
        value: ApprovalDocument;
    }[];
}

Parameters

Name	Type	Required	Description
requests	{ id: string; revision: number; value: ApprovalDocument; }[]	Yes	Visible approval records containing ID, optimistic revision and persisted request value.

Returns

Type declaration; no runtime value.

See also

ApprovalService for a complete host integration example.

Public members

requests

Visible approval records containing ID, optimistic revision and persisted request value.

requests[].id

Persisted approval record identifier.

requests[].revision

Positive optimistic approval revision sent with decisions/withdrawals.

requests[].value

Controlled field value; the host must update it in response to onChange.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] ApprovalOptions

Host-owned approval persistence, authorization and template/binding verification.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/service.

Signature

interface ApprovalOptions {
    store: PluginRecordStore<ApprovalDocument>;
    authorize(principal: PluginPrincipal, action: 'submit' | 'read' | 'decide' | 'withdraw', document?: ApprovalDocument): Promise<boolean>;
    resolveTemplate(principal: PluginPrincipal, templateId: string, input: {
        targetType: string;
        targetId: string;
    }): Promise<ApprovalTemplate | null>;
    verifyBinding?(principal: PluginPrincipal, binding: ApprovalBinding): Promise<boolean>;
}

Parameters

Name	Type	Required	Description
store	PluginRecordStore<ApprovalDocument>	Yes	Tenant-isolated durable approval record store with atomic compare-and-swap replace.
authorize	Promise<boolean>	Yes	Must check current lifecycle, membership and action/resource permission on every call; document is supplied when available.
resolveTemplate	Promise<ApprovalTemplate | null>	Yes	Resolve a current authorized template for the principal and target; null makes submission unavailable.
verifyBinding	Promise<boolean>	No	Required when submitting a bound request; verify input/contract hashes against the real host proposal/action and return true, rather than trusting request data.

Returns

Type declaration; no runtime value.

See also

ApprovalService for a complete host integration example.

Public members

store

Tenant-isolated durable approval record store with atomic compare-and-swap replace.

authorize

Must check current lifecycle, membership and action/resource permission on every call; document is supplied when available.

Parameters:

• principal: Verified tenant principal for this operation.
• action: Requested plugin action to authorize against current state.
• document: Current persisted approval document when available.

Returns: True only when current host policy allows access; false denies access.

Remarks

Must check current lifecycle, membership and action/resource permission on EVERY call.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { ApprovalOptions, ApprovalDocument } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function canReadApproval(options: ApprovalOptions, principal: PluginPrincipal, document: ApprovalDocument) {
 return options.authorize(principal, 'read', document);
}

resolveTemplate

Resolve a current authorized template for the principal and target; null makes submission unavailable.

Parameters:

• principal: Verified tenant principal for this operation.
• templateId: Host template key selected by the caller.
• input: Operation input validated and authorized by the host.

Returns: The authorized stage template, or null when unavailable.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { ApprovalOptions } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function resolveCurrentTemplate(options: ApprovalOptions, principal: PluginPrincipal, templateId: string, targetType: string, targetId: string) {
 return options.resolveTemplate(principal, templateId, { targetType, targetId }); // May resolve null.
}

resolveTemplate.input.targetType

Host resource type being reviewed; resolve a template only for the principal’s currently authorized target.

resolveTemplate.input.targetId

Exact host resource ID being reviewed; template selection must respect its current tenant/resource admission.

verifyBinding

Required when submitting a bound request; verify input/contract hashes against the real host proposal/action and return true, rather than trusting request data.

Parameters:

• principal: Verified tenant principal for this operation.
• binding: Action binding to compare against the real host proposal/contract.

Returns: True only when the real proposal/action matches the supplied binding.

Remarks

A request body cannot prove its own input/contract hash; the host verifies it against its proposal/action.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { ApprovalOptions } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function verifyHostBinding(options: ApprovalOptions, principal: PluginPrincipal, binding: Parameters<NonNullable<ApprovalOptions['verifyBinding']>>[1]) {
 if (!options.verifyBinding) throw new Error('Host binding verification is required');
 return options.verifyBinding(principal, binding);
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] ApprovalPage

Renders approval requests, submission and current-stage decision/withdrawal forms.

The host supplies live-authenticated transports; decision eligibility is enforced by the service.

Imports: @alneas/eaos-plugin-approval/react, @alneas/eaos-plugin-approval/workspace.

Signature

declare function ApprovalPage(): React.JSX.Element;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

React.JSX.Element

The workspace page with loading/error state, or an alert when the host provider is missing.

Remarks

Requires React,

Example

import * as React from 'react';
import { ApprovalPage, ApprovalProvider } from '@alneas/eaos-plugin-approval/workspace';
export function Page(props: Omit<React.ComponentProps<typeof ApprovalProvider>, 'children'>) { return <ApprovalProvider {...props}><ApprovalPage/></ApprovalProvider>; }

[FUNCTION] ApprovalProvider

Provides an isolated authenticated session for the plugin workspace.

Imports: @alneas/eaos-plugin-approval/react, @alneas/eaos-plugin-approval/workspace.

Signature

declare const ApprovalProvider: ({ tenantId, recordId, sessionKey, client, children }: _alneas_eaos_react.WorkspaceProviderProps<ApprovalList>) => React.DetailedReactHTMLElement<{
    role: "status";
}, HTMLElement> | React.FunctionComponentElement<React.ProviderProps<_alneas_eaos_react.WorkspaceClient<ApprovalList> | null>>;

Parameters

Name	Type	Required	Description
{ tenantId, recordId, sessionKey, client, children }	_alneas_eaos_react.WorkspaceProviderProps<ApprovalList>	Yes	WorkspaceProviderProps containing verified tenant/resource/session IDs, stable client and children.

Returns

React.DetailedReactHTMLElement<{ role: "status"; }, HTMLElement> \| React.FunctionComponentElement<React.ProviderProps<_alneas_eaos_react.WorkspaceClient<ApprovalList> \| null>>

Children after the session is ready, otherwise loading/unavailable status content.

Remarks

Closes old UI sessions on scope change/unmount. The host owns transport authentication and authorization; see ApprovalPage for setup.

Example

import * as React from 'react';
import { ApprovalPage, ApprovalProvider } from '@alneas/eaos-plugin-approval/workspace';
export function Page(props: Omit<React.ComponentProps<typeof ApprovalProvider>, 'children'>) { return <ApprovalProvider {...props}><ApprovalPage/></ApprovalProvider>; }

[FUNCTION] ApprovalRequestForm

Renders a schema-driven plugin command form backed by a host callback.

Host supplies an authenticated command transport; no direct database writes.

Imports: @alneas/eaos-plugin-approval/react.

Signature

declare function ApprovalRequestForm({ submit, labels }: {
    submit(values: {
        templateId: string;
        title: string;
        targetType: string;
        targetId: string;
    }): Promise<void>;
    labels: {
        templateId: string;
        title: string;
        targetType: string;
        targetId: string;
    };
}): React.JSX.Element;

Parameters

Name	Type	Required	Description
{ submit, labels }	{ submit(values: { templateId: string; title: string; targetType: string; targetId: string; }): Promise<void>; labels: { templateId: string; title: string; targetType: string; targetId: string; }; }	Yes	submit is an authenticated async host command and labels supplies field captions. Submission values contain templateId/title/targetType/targetId; all four fields are required.

Returns

React.JSX.Element

A plugin help panel and react-tools FormView in create mode.

Remarks

Requires React,

Public members

argument1.submit

Authenticated host submission callback; receives the four required request fields and resolves on completion.

Parameters:

• values: Four required approval request fields; the host must authorize the actual target and template.

Returns: Resolves without a value when the host command completes; the form handles its Promise outcome.

Errors and rejections

Rejects host authorization, validation, transport or persistence failures; reload current state after uncertain write outcomes.

Example:

import { ApprovalRequestForm } from '@alneas/eaos-plugin-approval/react';
type HostCommand = Parameters<typeof ApprovalRequestForm>[0]['submit'];
export async function runHostCommand(command: HostCommand, values: Parameters<HostCommand>[0]) {
 await command(values);
}

argument1.submit.values.templateId

Host approval-template identifier.

argument1.submit.values.title

Human-readable request title.

argument1.submit.values.targetType

Host resource type being reviewed.

argument1.submit.values.targetId

Host resource ID being reviewed.

argument1.labels

Plugin field captions rendered by the command form.

argument1.labels.templateId

Host approval-template identifier.

argument1.labels.title

Human-readable request title.

argument1.labels.targetType

Host resource type being reviewed.

argument1.labels.targetId

Host resource ID being reviewed.

Example

import * as React from 'react';
import { ApprovalRequestForm } from '@alneas/eaos-plugin-approval/react';
export function Form({ submit }: Pick<React.ComponentProps<typeof ApprovalRequestForm>, 'submit'>) { return <ApprovalRequestForm submit={submit} labels={{ templateId: 'Approval rule', title: 'Title', targetType: 'Target type', targetId: 'Target ID' }}/>; }

[CLASS] ApprovalService

Persists tenant-scoped staged approvals with live host authorization and optimistic revision checks.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/service.

Signature

declare class ApprovalService {
    constructor(options: ApprovalOptions);
    submit(p: PluginPrincipal, input: Record<string, unknown>): Promise<PluginRecord<ApprovalDocument>>;
    read(p: PluginPrincipal, id: string): Promise<PluginRecord<ApprovalDocument>>;
    list(p: PluginPrincipal, limit?: number): Promise<PluginRecord<ApprovalDocument>[]>;
    decide(p: PluginPrincipal, id: string, input: Record<string, unknown>): Promise<{
        id: string;
        revision: number;
        value: ApprovalDocument;
    }>;
    withdraw(p: PluginPrincipal, id: string, expected: number): Promise<{
        id: string;
        revision: number;
        value: ApprovalDocument;
    }>;
}

Parameters

Name	Type	Required	Description
options	ApprovalOptions	Yes	Live authorization/template callbacks and tenant-isolated store; optional binding verifier is mandatory for bound submissions.

Returns

ApprovalService

Remarks

Requires server runtime, canonical platform-records validation and a tenant-isolated durable store. No automatic retries or idempotency keys are added. Failed responses may follow committed writes; reload before retrying. Templates, role assignments and binding verification belong to the host.

Constructor contract

Public members

submit

Creates a pending approval by copying the host-resolved stage template and recording its requester.

Parameters:

• p: Verified current tenant principal.
• input: Exactly templateId/title/targetType/targetId plus optional binding; title is limited to 1000 characters.

Returns: The newly stored record with generated ID and revision 1.

Remarks

A provided binding must match requester/tenant/target and pass verifyBinding. Templates contain 1–50 unique stages with user/role assignments; self approval defaults to false. Submission is not idempotent.

Errors and rejections

Rejects malformed input/template (400), denied authorization/binding (403), and host resolver/store failures.

Example:

import { ApprovalService } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function request(service: ApprovalService, principal: PluginPrincipal, templateId: string) { return service.submit(principal, { templateId, title: 'Review report', targetType: 'report', targetId: 'sample' }); }

read

Reads one approval after both general and document-level authorization.

Parameters:

• p: Verified current principal.
• id: Nonblank approval record ID.

Returns: The persisted approval record.

Errors and rejections

Rejects missing record (404), denied access (403), invalid ID or propagated store/authorization failures.

Example:

import { ApprovalService } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function read(service: ApprovalService, principal: PluginPrincipal, id: string) { return service.read(principal, id); }

list

Lists approval records and filters out documents denied by live host authorization.

Parameters:

• p: Verified current principal.
• limit: Store list bound; defaults to 50 and is validated by the host store.

Returns: Authorized records in store order, possibly empty or fewer than limit.

Remarks

General read access is checked before and after filtering. This method does not expose pagination metadata.

Errors and rejections

Rejects denied general access or propagated store/authorization failures.

Example:

import { ApprovalService } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function list(service: ApprovalService, principal: PluginPrincipal) { return service.list(principal, 25); }

decide

Applies one authorized current-stage decision and persists it with compare-and-swap.

Parameters:

• p: Verified current principal.
• id: Approval record ID.
• input: Exactly positive revision, action approve/reject and optional nonblank comment up to 4000 characters.

Returns: The next-revision record; final decisions include a validated decisionReceipt, intermediate approvals advance currentStage.

Remarks

Only assigned users/roles can decide; self approval requires template permission. A stale retry can conflict after a successful write.

Errors and rejections

Rejects invalid input (400), denied/self/unassigned decision (403), missing record (404), stale/finalized state or CAS conflict (409), and host failures.

Example:

import { ApprovalService } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function approve(service: ApprovalService, principal: PluginPrincipal, id: string, revision: number) { return service.decide(principal, id, { revision, action: 'approve' }); }

withdraw

Withdraws a pending request only for its original requester and expected revision.

Parameters:

• p: Verified requester principal.
• id: Approval record ID.
• expected: Positive persisted revision to compare-and-swap.

Returns: The next-revision record with withdrawn status and a history entry.

Errors and rejections

Rejects invalid revision, denied/nonrequester access (403), missing record (404), changed/finalized state or CAS conflict (409), and host failures.

Example:

import { ApprovalService } from '@alneas/eaos-plugin-approval/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function withdraw(service: ApprovalService, principal: PluginPrincipal, id: string, revision: number) { return service.withdraw(principal, id, revision); }

Example

import { ApprovalService, type ApprovalOptions } from '@alneas/eaos-plugin-approval/service';
export function connectApproval(options: ApprovalOptions) { return new ApprovalService(options); }

[INTERFACE] ApprovalStage

One ordered approval stage assigned to explicit users or roles.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/service.

Signature

interface ApprovalStage {
    id: string;
    label: string;
    userIds?: string[];
    roles?: string[];
}

Parameters

Name	Type	Required	Description
id	string	Yes	Unique nonblank stage identifier within its template.
label	string	Yes	Nonblank presentation caption.
userIds	string[]	No	Optional explicit assigned users; at least one user or role assignment is required.
roles	string[]	No	Optional assigned roles checked against current principal roles.

Returns

Type declaration; no runtime value.

See also

ApprovalService for a complete host integration example.

Public members

id

Unique nonblank stage identifier within its template.

label

Nonblank presentation caption.

userIds

Optional explicit assigned users; at least one user or role assignment is required.

roles

Optional assigned roles checked against current principal roles.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] ApprovalTemplate

Host-selected immutable stage template copied into a submitted request.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/service.

Signature

interface ApprovalTemplate {
    id: string;
    stages: ApprovalStage[];
    allowSelfApproval?: boolean;
}

Parameters

Name	Type	Required	Description
id	string	Yes	Host template identifier matching the requested templateId.
stages	ApprovalStage[]	Yes	Ordered 1–50 stage assignments copied into the request.
allowSelfApproval	boolean	No	Whether an assigned requester can approve their own request.

Returns

Type declaration; no runtime value.

See also

ApprovalService for a complete host integration example.

Public members

id

Host template identifier matching the requested templateId.

stages

Ordered 1–50 stage assignments copied into the request.

allowSelfApproval

Whether an assigned requester can approve their own request.

Default: false.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] ConditionalStep

Conditional rule that appends a host-defined step when one field comparison matches.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/rules.

Signature

interface ConditionalStep<T> {
    field: string;
    operator: '>=' | '>' | '===' | '<=' | '<';
    value: number | string;
    step: T;
}

Parameters

Name	Type	Required	Description
field	string	Yes	Input values key inspected by the rule.
operator	'>=' | '>' | '===' | '<=' | '<'	Yes	String-coercing equality or finite-number comparison operator.
value	number | string	Yes	Comparison threshold or equality text.
step	T	Yes	Host-defined step appended when the condition matches.

Returns

Type declaration; no runtime value.

Type parameters

• T: Host value shape carried by this contract.

See also

ApprovalService for a complete host integration example.

Public members

field

Input values key inspected by the rule.

operator

String-coercing equality or finite-number comparison operator.

value

Comparison threshold or equality text.

step

Host-defined step appended when the condition matches.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] createExtension

Builds a host extension restricted to a verified, concrete tenant catalog.

Imports: @alneas/eaos-plugin-approval/runtime.

Signature

declare function createExtension(input: {
    tenantIds: string[];
    bindings?: PublicPluginBindings;
}): {
    apiVersion: 1;
    id: string;
    tenantIds: string[];
    manifests: _alneas_eaos_core.PluginManifest[];
    lifecycle: _alneas_eaos_server_lifecycle_engine.LifecyclePlugin[];
    routeFactories: {
        [x: string]: (options?: any) => any;
    };
};

Parameters

Name	Type	Required	Description
input	{ tenantIds: string[]; bindings?: PublicPluginBindings; }	Yes	Nonempty distinct concrete tenantIds plus required live bindings; wildcard IDs are rejected.

Returns

{ apiVersion: 1; id: string; tenantIds: string[]; manifests: _alneas_eaos_core.PluginManifest[]; lifecycle: _alneas_eaos_server_lifecycle_engine.LifecyclePlugin[]; routeFactories: { [x: string]: (options?: any) => any; }; }

An API-version-1 extension containing tenant IDs, configured manifest, lifecycle and route factories.

Remarks

This validates adapter presence and tenant admission, not the truth of host authorization. No activation or migration is executed. Principals outside the configured catalog resolve to null.

Errors and rejections

Error for empty/duplicate/wildcard tenant IDs or missing host adapter functions.

Public members

input.tenantIds

Verified nonempty catalog of distinct concrete tenant IDs; wildcards are rejected.

input.bindings

Required live host options and identity resolver; omitted bindings throw.

Example

import { createExtension, type PublicPluginBindings } from '@alneas/eaos-plugin-approval/runtime';
export function configureExtension(tenantIds: string[], bindings: PublicPluginBindings) { return createExtension({ tenantIds, bindings }); }

[FUNCTION] createPlugin

Binds static plugin metadata to the host-configured route factory.

Imports: @alneas/eaos-plugin-approval.

Signature

declare function createPlugin(options: ApprovalOptions, resolvePrincipal: (c: Context) => Promise<PluginPrincipal | null>): PluginManifest;

Parameters

Name	Type	Required	Description
options	ApprovalOptions	Yes	Live host configuration; see ApprovalOptions.
resolvePrincipal	(c: Context) => Promise<PluginPrincipal | null>	Yes	Current authenticated Hono principal resolver; null denies admission.

Returns

PluginManifest

A cloned PluginManifest with a createRoutes closure; no routes are instantiated until called.

Remarks

Supplying a manifest does not activate a tenant or perform migrations. Host admission and live authorization remain mandatory.

Example

import { createPlugin, type ApprovalOptions } from '@alneas/eaos-plugin-approval';
export function configure(options: ApprovalOptions, resolvePrincipal: Parameters<typeof createPlugin>[1]) { return createPlugin(options, resolvePrincipal); }

[FUNCTION] createRoutes

Creates tenant-scoped approval request, decision and withdrawal routes.

Imports: @alneas/eaos-plugin-approval.

Signature

declare function createRoutes(options: ApprovalOptions, resolvePrincipal: (c: Context) => Promise<PluginPrincipal | null>): hono.Hono<_alneas_eaos_server_plugin_data.PluginHttpEnv, hono_types.BlankSchema, "/">;

Parameters

Name	Type	Required	Description
options	ApprovalOptions	Yes	Live host persistence and authorization configuration; see ApprovalOptions.
resolvePrincipal	(c: Context) => Promise<PluginPrincipal | null>	Yes	Resolves current authenticated principal per Hono request, or null to deny access.

Returns

hono.Hono<_alneas_eaos_server_plugin_data.PluginHttpEnv, hono_types.BlankSchema, "/">

A Hono router ready to mount under the plugin API prefix.

Remarks

The host owns authentication, current tenant membership and plugin activation. Service errors become HTTP failures through the plugin router; adapter failures may propagate. Mutations can commit before a response failure; reload current state before retrying.

Example

import { createRoutes, type ApprovalOptions } from '@alneas/eaos-plugin-approval';
export function connectRoutes(options: ApprovalOptions, resolvePrincipal: Parameters<typeof createRoutes>[1]) {
 return createRoutes(options, resolvePrincipal);
}

[FUNCTION] default

Renders the plugin’s bundled repository-authored user guide.

Imports: @alneas/eaos-plugin-approval/user-help.

Signature

declare function UserHelp(): React.JSX.Element;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

React.JSX.Element

A collapsible UserGuide element containing static Japanese help.

Remarks

Requires React and

Example

import * as React from 'react';
import UserHelp from '@alneas/eaos-plugin-approval/user-help';
export function Help() { return <UserHelp/>; }

[FUNCTION] expandApprovalSteps

Expands matching conditional approval steps, sorts by stepOrder and keeps the first step for each order.

Deterministic rule expansion. Roles, names, limits and templates are host-owned.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/rules.

Signature

declare function expandApprovalSteps<T extends {
    stepOrder: number;
}>(rules: {
    defaultSteps: T[];
    conditions?: ConditionalStep<T>[];
}, values: Record<string, unknown>): T[];

Parameters

Name	Type	Required	Description
rules	{ defaultSteps: T[]; conditions?: ConditionalStep<T>[]; }	Yes	Default steps plus optional conditions evaluated against values.
values	Record<string, unknown>	Yes	Field-value map; null/undefined values do not match.

Returns

T[]

A new sorted array sharing the original step objects; duplicate stepOrder values are removed.

Type parameters

• T: Host step shape with numeric stepOrder; other fields are preserved.

Remarks

Equality compares String values. Ordering operators coerce finite numbers; nonfinite comparisons are skipped. Default steps win duplicate orders ahead of appended conditions.

Public members

rules.defaultSteps

Host steps always included before conditional expansion.

rules.conditions

Optional field comparisons that append matching steps; defaults to none.

Example

import { expandApprovalSteps } from '@alneas/eaos-plugin-approval/rules';
const steps = expandApprovalSteps({ defaultSteps: [{ stepOrder: 1, role: 'reviewer' }], conditions: [{ field: 'amount', operator: '>=', value: 1000, step: { stepOrder: 2, role: 'manager' } }] }, { amount: 2000 });

[CONSTANT] lifecycle

Declares lifecycle compatibility and schema dependencies for host orchestration.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/lifecycle.

Signature

declare const lifecycle: LifecyclePlugin;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Remarks

The host lifecycle engine owns installation and tenant admission; importing this value performs no migrations.

Example

import { lifecycle } from '@alneas/eaos-plugin-approval'
console.log(lifecycle.id, lifecycle.version)

[CONSTANT] manifest

Declares static plugin metadata, navigation, public storage contracts and API prefix.

Static metadata shared by documentation inspection and the host-configured factory.

Imports: @alneas/eaos-plugin-approval/manifest.

Signature

declare const manifest: PluginManifest;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Remarks

Inspection metadata only; use the package createPlugin factory with live host bindings to obtain routes. This declaration does not activate a tenant.

Example

import { manifest } from '@alneas/eaos-plugin-approval/manifest'
console.log(manifest.id, manifest.version)

[INTERFACE] PublicPluginBindings

Live host service configuration and current authenticated principal resolver.

Imports: @alneas/eaos-plugin-approval/runtime.

Signature

interface PublicPluginBindings {
    options: ApprovalOptions;
    resolvePrincipal(context: Context): Promise<PluginPrincipal | null>;
}

Parameters

Name	Type	Required	Description
options	ApprovalOptions	Yes	Live plugin service/storage/authorization configuration.
resolvePrincipal	Promise<PluginPrincipal | null>	Yes	Resolve current verified Hono request identity, or null to deny access; rejection propagates.

Returns

Type declaration; no runtime value.

See also

ApprovalService for a complete host integration example.

Public members

options

Live plugin service/storage/authorization configuration.

resolvePrincipal

Resolve current verified Hono request identity, or null to deny access; rejection propagates.

Parameters:

• context: Current Hono request context.

Returns: A verified current principal, or null to deny admission.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { PublicPluginBindings } from '@alneas/eaos-plugin-approval/runtime';
export function resolveRequest(bindings: PublicPluginBindings, context: Parameters<PublicPluginBindings['resolvePrincipal']>[0]) {
 return bindings.resolvePrincipal(context); // Null denies unauthenticated or unavailable identity.
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] recordSchema

Exposes the canonical platform-records schema used by the plugin storage contract.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/lifecycle.

Signature

declare const recordSchema: Record<string, unknown>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Remarks

This references getPlatformRecordsContract().schema; the plugin does not own a separate table schema.

Example

import { recordSchema } from '@alneas/eaos-plugin-approval'
console.log(recordSchema.type, recordSchema.properties)

[FUNCTION] validateApprovalDecisionReceipt

Validates a final approval decision receipt and copies its accepted public fields.

Imports: @alneas/eaos-plugin-approval, @alneas/eaos-plugin-approval/service.

Signature

declare function validateApprovalDecisionReceipt(value: unknown): ApprovalDecisionReceipt;

Parameters

Name	Type	Required	Description
value	unknown	Yes	Untrusted final approved/rejected receipt; requires positive revision, parseable time and nonblank bounded identifiers.

Returns

ApprovalDecisionReceipt

A normalized receipt with a copied actorRoles array; unknown fields are omitted.

Remarks

This validates shape, not authenticity or host authorization. bindingHash is bounded text, not independently recomputed here.

Errors and rejections

Error for invalid shape, decision, roles, timing or bounded text fields.

Example

import { validateApprovalDecisionReceipt } from '@alneas/eaos-plugin-approval/service';
const receipt = validateApprovalDecisionReceipt({ receiptId: 'receipt-1', approvalId: 'request-1', tenantId: 'sample', decision: 'approved', actorId: 'reviewer', actorRoles: ['reviewer'], stageId: 'review', decidedAt: '2026-01-01T00:00:00Z', revision: 2 });