コンテンツにスキップ

@alneas/eaos-plugin-field-customization API

@alneas/eaos-plugin-field-customization API

Section titled “@alneas/eaos-plugin-field-customization API”
Import Contract
@alneas/eaos-plugin-field-customization/schema Typed public export
@alneas/eaos-plugin-field-customization/lifecycle Typed public export
@alneas/eaos-plugin-field-customization/react Typed public export
@alneas/eaos-plugin-field-customization/workspace Typed public export
@alneas/eaos-plugin-field-customization/user-help Typed public export
@alneas/eaos-plugin-field-customization Typed public export
@alneas/eaos-plugin-field-customization/service Typed public export
@alneas/eaos-plugin-field-customization/manifest Typed public export
@alneas/eaos-plugin-field-customization/runtime Typed public export
@alneas/eaos-plugin-field-customization/user-guide.json Packaged JSON contract/data asset; resolve this exported path with the host loader
@alneas/eaos-plugin-field-customization/deployment.json Packaged JSON contract/data asset; resolve this exported path with the host loader

Projects display overrides and additive custom fields onto a cloned object schema.

Pure projection: existing validation constraints are never removed or weakened.

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/react, @alneas/eaos-plugin-field-customization/schema.

declare function applyFieldCustomizations<T extends ObjectSchema>(base: T, fields: Record<string, FieldCustomization>): T;
Name Type Required Description
base T Yes Canonical object schema; original validation constraints are preserved.
fields Record<string, FieldCustomization> Yes Overrides keyed by field name; new custom_ fields require a supported explicit type.

T

A deep-cloned schema with display metadata and added required fields.

  • T: JSON-schema-like object shape preserved by the projection.

This pure projection does not validate all service input constraints. Existing field types/enums remain unchanged; false is_required never removes a base requirement. Prototype keys and unknown non-custom fields are skipped.

May throw if base contains values unsupported by structuredClone.

import { applyFieldCustomizations } from '@alneas/eaos-plugin-field-customization/schema';
const schema = applyFieldCustomizations({ type: 'object', properties: { title: { type: 'string' } } }, { title: { display_label: 'Report title' }, custom_note: { type: 'string', help_text: 'Optional note' } });

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

Imports: @alneas/eaos-plugin-field-customization/runtime.

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;
};
};
Name Type Required Description
input { tenantIds: string[]; bindings?: PublicPluginBindings; } Yes Nonempty distinct concrete tenantIds plus required live bindings; wildcard IDs are rejected.

{ 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.

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.

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

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

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

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

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

Imports: @alneas/eaos-plugin-field-customization.

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

PluginManifest

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

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

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

Creates tenant-scoped field definition read/write routes.

Imports: @alneas/eaos-plugin-field-customization.

declare function createRoutes(options: FieldCustomizationOptions, resolvePrincipal: (c: Context) => Promise<PluginPrincipal | null>): hono.Hono<_alneas_eaos_server_plugin_data.PluginHttpEnv, hono_types.BlankSchema, "/">;
Name Type Required Description
options FieldCustomizationOptions Yes Live host persistence and authorization configuration; see FieldCustomizationOptions.
resolvePrincipal (c: Context) => Promise<PluginPrincipal | null> Yes Resolves current authenticated principal per Hono request, or null to deny access.

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

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

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.

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

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

Imports: @alneas/eaos-plugin-field-customization/user-help.

declare function UserHelp(): React.JSX.Element;
Name Type Required Description
— — — No call parameters.

React.JSX.Element

A collapsible UserGuide element containing static Japanese help.

Requires React and

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

Display overrides and additive validation requirements for one schema field.

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/schema.

interface FieldCustomization {
display_label?: string;
placeholder?: string;
help_text?: string;
is_required?: boolean;
is_hidden?: boolean;
display_order?: number;
type?: 'string' | 'number' | 'boolean';
enum?: string[];
}
Name Type Required Description
display_label string No Optional displayed field title, at most 2000 characters through the service.
placeholder string No Optional input hint, at most 2000 characters.
help_text string No Optional schema description/help, at most 2000 characters.
is_required boolean No True adds a requirement; false never removes base requirements.
is_hidden boolean No Display-only hidden flag; required base fields cannot be hidden through the service.
display_order number No Optional safe integer UI order with absolute value at most 10000.
type 'string' | 'number' | 'boolean' No Required for a new custom_ field; forbidden for existing base fields.
enum string[] No Nonempty list of at most 100 strings for new string fields only; each at most 2000 characters.

Type declaration; no runtime value.

FieldCustomizationService for a complete host integration example.

Optional displayed field title, at most 2000 characters through the service.

Optional input hint, at most 2000 characters.

Optional schema description/help, at most 2000 characters.

True adds a requirement; false never removes base requirements.

Display-only hidden flag; required base fields cannot be hidden through the service.

Optional safe integer UI order with absolute value at most 10000.

Required for a new custom_ field; forbidden for existing base fields.

Nonempty list of at most 100 strings for new string fields only; each at most 2000 characters.

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

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

Saves one display override through the host command transport; host carries resource/revision.

Imports: @alneas/eaos-plugin-field-customization/react.

declare function FieldCustomizationForm({ save, labels }: {
save(values: FieldCustomization): Promise<void>;
labels: {
display_label: string;
placeholder: string;
help_text: string;
is_hidden: string;
is_required: string;
};
}): React.JSX.Element;
Name Type Required Description
{ save, labels } { save(values: FieldCustomization): Promise<void>; labels: { display_label: string; placeholder: string; help_text: string; is_hidden: string; is_required: string; }; } Yes save is an authenticated async host command and labels supplies field captions. Save receives display overrides; host closes over resource, field key and revision.

React.JSX.Element

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

Requires React,

Authenticated host field override callback; closes over authorized resource/field/revision and resolves on completion.

Parameters:

  • values: Display overrides for the host-selected field/resource; the host supplies the current definition revision.

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

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

Example:

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

Plugin field captions rendered by the command form.

Display-label input caption.

Placeholder input caption.

Help-text input caption.

Hidden-state input caption.

Required-state input caption.

import * as React from 'react';
import { FieldCustomizationForm } from '@alneas/eaos-plugin-field-customization/react';
export function Form({ save }: Pick<React.ComponentProps<typeof FieldCustomizationForm>, 'save'>) { return <FieldCustomizationForm save={save} labels={{ display_label: 'Label', placeholder: 'Placeholder', help_text: 'Help', is_hidden: 'Hidden', is_required: 'Required' }}/>; }

Tenant-isolated field storage with live resource authorization and base schema resolution.

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/service.

interface FieldCustomizationOptions {
store: PluginRecordStore<FieldDefinition>;
authorize(principal: PluginPrincipal, action: 'read' | 'write', resource: string): Promise<boolean>;
resolveSchema(principal: PluginPrincipal, resource: string): Promise<ObjectSchema | null>;
}
Name Type Required Description
store PluginRecordStore<FieldDefinition> Yes Tenant/resource-isolated durable definition storage with atomic compare-and-swap replace.
authorize Promise<boolean> Yes Live lifecycle, membership and resource permission check for read/write; false denies access.
resolveSchema Promise<ObjectSchema | null> Yes Resolve the current canonical object schema for an authorized resource; null makes the resource unavailable.

Type declaration; no runtime value.

FieldCustomizationService for a complete host integration example.

Tenant/resource-isolated durable definition storage with atomic compare-and-swap replace.

Live lifecycle, membership and resource permission check for read/write; false denies access.

Parameters:

  • principal: Verified tenant principal for this operation.
  • action: Requested plugin action to authorize against current state.
  • resource: Host-catalog resource identifier.

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

Must check live lifecycle, membership and resource permission.

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

Example:

import type { FieldCustomizationOptions } from '@alneas/eaos-plugin-field-customization/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function canReadFields(options: FieldCustomizationOptions, principal: PluginPrincipal, resource: string) {
return options.authorize(principal, 'read', resource);
}

Resolve the current canonical object schema for an authorized resource; null makes the resource unavailable.

Parameters:

  • principal: Verified tenant principal for this operation.
  • resource: Host-catalog resource identifier.

Returns: The canonical object schema, or null when unavailable.

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

Example:

import type { FieldCustomizationOptions } from '@alneas/eaos-plugin-field-customization/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function resolveCurrentSchema(options: FieldCustomizationOptions, principal: PluginPrincipal, resource: string) {
return options.resolveSchema(principal, resource); // May resolve null when the resource is unavailable.
}

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

Renders per-resource field overrides with revision-aware save and refresh controls.

Mount one provider per authorized resource; resource selection belongs to the host catalog.

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

declare function FieldCustomizationPage(): React.JSX.Element;
Name Type Required Description
— — — No call parameters.

React.JSX.Element

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

Requires React,

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

Provides an isolated authenticated session for the plugin workspace.

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

declare const FieldCustomizationProvider: ({ tenantId, recordId, sessionKey, client, children }: _alneas_eaos_react.WorkspaceProviderProps<FieldWorkspaceData>) => React.DetailedReactHTMLElement<{
role: "status";
}, HTMLElement> | React.FunctionComponentElement<React.ProviderProps<_alneas_eaos_react.WorkspaceClient<FieldWorkspaceData> | null>>;
Name Type Required Description
{ tenantId, recordId, sessionKey, client, children } _alneas_eaos_react.WorkspaceProviderProps<FieldWorkspaceData> Yes WorkspaceProviderProps containing verified tenant/resource/session IDs, stable client and children.

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

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

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

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

Reads and revision-checks tenant/resource field overrides without weakening base schema validation.

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/service.

declare class FieldCustomizationService {
constructor(options: FieldCustomizationOptions);
read(p: PluginPrincipal, resource: string): Promise<{
id: string;
revision: number;
fields: Record<string, FieldCustomization>;
schema: ObjectSchema;
}>;
write(p: PluginPrincipal, resource: string, input: Record<string, unknown>): Promise<{
id: string;
revision: number;
fields: Record<string, FieldCustomization>;
schema: ObjectSchema;
}>;
}
Name Type Required Description
options FieldCustomizationOptions Yes Tenant-isolated storage, live resource authorization and canonical object schema resolver.

FieldCustomizationService

Server-side host supplies current resource authorization, canonical object schema resolution and durable isolated storage. A write can persist before a final authorization check rejects; reload current state before retrying.

Reads a resource definition and merges its overrides into the current canonical schema.

Parameters:

  • p: Verified tenant principal.
  • resource: Nonblank host-catalog resource ID.

Returns: Resource ID, revision, fields and projected schema; absent definitions use revision 0 and empty fields.

Rejects invalid principal/resource, denied/revoked access (403), unavailable object schema (404), and propagated host failures.

Example:

import { FieldCustomizationService } from '@alneas/eaos-plugin-field-customization/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function readFields(service: FieldCustomizationService, principal: PluginPrincipal, resource: string) { return service.read(principal, resource); }

Replaces the complete field override map using resource-scoped optimistic concurrency.

Parameters:

  • p: Verified current tenant principal.
  • resource: Host-catalog resource ID.
  • input: Exactly revision (nonnegative integer, 0 for new definition) and fields (at most 100 overrides).

Returns: The new definition revision, copied fields and projected schema.

Omitted fields are removed. Existing required base fields cannot be hidden or weakened; new names use custom_ prefix and a supported scalar type. Text is limited to 2000 characters, order magnitude to 10000 and string enum choices to 100. Final authorization occurs after persistence, so a rejection may follow a committed write.

Rejects malformed/weakening overrides (400), denied/revoked access (403), unavailable schema (404), stale revision/CAS conflict (409), and host failures.

Example:

import { FieldCustomizationService } from '@alneas/eaos-plugin-field-customization/service';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export async function renameTitle(service: FieldCustomizationService, principal: PluginPrincipal, resource: string) {
const current = await service.read(principal, resource);
return service.write(principal, resource, { revision: current.revision, fields: { ...current.fields, title: { ...current.fields.title, display_label: 'Report title' } } });
}
import { FieldCustomizationService, type FieldCustomizationOptions } from '@alneas/eaos-plugin-field-customization/service';
export function connectFields(options: FieldCustomizationOptions) { return new FieldCustomizationService(options); }

Complete persisted override map for one host resource.

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/service.

interface FieldDefinition {
fields: Record<string, FieldCustomization>;
}
Name Type Required Description
fields Record<string, FieldCustomization> Yes Complete resource override map; service writes replace this map rather than merging omitted keys.

Type declaration; no runtime value.

FieldCustomizationService for a complete host integration example.

Complete resource override map; service writes replace this map rather than merging omitted keys.

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

Resource definition, revision and merged canonical schema returned to the workspace.

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

interface FieldWorkspaceData extends FieldDefinition {
id: string;
revision: number;
schema: ObjectSchema;
}
Name Type Required Description
id string Yes Authorized resource identifier.
revision number Yes Persisted field-definition revision; 0 when no definition exists.
schema ObjectSchema Yes Canonical base schema projected with stored field overrides.

Type declaration; no runtime value.

FieldCustomizationService for a complete host integration example.

Authorized resource identifier.

Persisted field-definition revision; 0 when no definition exists.

Canonical base schema projected with stored field overrides.

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

Declares lifecycle compatibility and schema dependencies for host orchestration.

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/lifecycle.

declare const lifecycle: LifecyclePlugin;
Name Type Required Description
— — — No call parameters.

Declared constant value.

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

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

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-field-customization/manifest.

declare const manifest: PluginManifest;
Name Type Required Description
— — — No call parameters.

Declared constant value.

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

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

Extensible JSON-schema-like object used for safe display projections.

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/schema.

interface ObjectSchema {
type?: string;
properties?: Record<string, any>;
required?: string[];
[key: string]: any;
}
Name Type Required Description
type string No Schema type; the service requires object.
properties Record<string, any> No Canonical property schemas; required by the service.
required string[] No Field keys whose validation requirement must be preserved.

Type declaration; no runtime value.

FieldCustomizationService for a complete host integration example.

Schema type; the service requires object.

Canonical property schemas; required by the service.

Field keys whose validation requirement must be preserved.

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

Live host service configuration and current authenticated principal resolver.

Imports: @alneas/eaos-plugin-field-customization/runtime.

interface PublicPluginBindings {
options: FieldCustomizationOptions;
resolvePrincipal(context: Context): Promise<PluginPrincipal | null>;
}
Name Type Required Description
options FieldCustomizationOptions 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.

Type declaration; no runtime value.

FieldCustomizationService for a complete host integration example.

Live plugin service/storage/authorization configuration.

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.

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

Example:

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

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

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

Imports: @alneas/eaos-plugin-field-customization, @alneas/eaos-plugin-field-customization/lifecycle.

declare const recordSchema: Record<string, unknown>;
Name Type Required Description
— — — No call parameters.

Declared constant value.

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

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