@nexia/sdk 0.5.0

package/dist/platform.d.ts

@@ -0,0 +1,378 @@
+import type { ComponentType, ReactElement, RefCallback } from 'react';
+import type { UseMutationResult, UseQueryResult } from '@tanstack/react-query';
+import type { LegalEntityContext, TenantContext } from './context';
+import type { ResourceListSchema } from './resources/resource-list';
+export interface OperatingUnitListItem {
+    public_id: string;
+    code: string;
+    name: string;
+    unit_type: string;
+    is_primary?: boolean;
+}
+export interface OperatingUnitContextResponse {
+    operating_units: OperatingUnitListItem[];
+}
+export type OperatingUnitQueryScope = 'memberships' | 'affiliated' | 'assignable';
+export type OperatingUnitSelectionResult = UseQueryResult<OperatingUnitContextResponse, Error> & {
+    operatingUnits: OperatingUnitListItem[];
+    selectedPublicId: string | null;
+    select: (publicId: string) => void;
+};
+export type OperatingUnitQueryResult = UseQueryResult<OperatingUnitContextResponse, Error>;
+export interface LegalEntityListItem {
+    public_id: string;
+    code: string;
+    name: string;
+    is_primary?: boolean;
+}
+export interface LegalEntityContextResponse {
+    legal_entities: LegalEntityListItem[];
+}
+export type LegalEntityQueryResult = UseQueryResult<LegalEntityContextResponse, Error>;
+/** Active tenant Legal Entities used only to set a tenant-owned record's domain applicability. */
+export interface LegalEntityApplicabilityResponse {
+    data: LegalEntityListItem[];
+}
+export type LegalEntityApplicabilityQueryResult = UseQueryResult<LegalEntityApplicabilityResponse, Error>;
+/** Core-owned Approval route-policy metadata exposed for App reference pickers. */
+export interface ApprovalRoutePolicyListItem {
+    id: string;
+    key: string;
+    version: number;
+    name: string;
+    status: 'draft' | 'active' | 'deprecated' | 'retired';
+    scope: 'tenant' | 'legal_entity';
+    legal_entity_public_id: string | null;
+}
+export interface ApprovalRoutePolicyListResponse {
+    data: ApprovalRoutePolicyListItem[];
+}
+export type ApprovalRoutePoliciesQueryResult = UseQueryResult<ApprovalRoutePolicyListResponse, Error>;
+/** Submitter-safe shared approval line from the record's Legal Entity. */
+export interface ApprovalSharedLine {
+    key: string;
+    name: string;
+    line_hash?: string;
+    resolved: boolean;
+    unavailable?: boolean;
+    stages: Array<{
+        position: number;
+        steps: Array<{
+            kind: string;
+            is_final_authority?: boolean;
+            user: {
+                id: number;
+                name: string;
+                email: string;
+            } | null;
+        }>;
+    }>;
+}
+export interface ApprovalSharedLinesResponse {
+    data: ApprovalSharedLine[];
+}
+export type ApprovalSharedLinesQueryResult = UseQueryResult<ApprovalSharedLinesResponse, Error>;
+/** Active or administratively visible participation in one Legal Entity. */
+export interface LegalEntityMemberListItem {
+    id: number;
+    public_id: string;
+    name: string;
+    email: string;
+    status: string;
+    party_public_id: string | null;
+    party_display_label: string | null;
+    title: string | null;
+    membership_status: string;
+    is_active_member: boolean;
+    is_primary: boolean;
+    legal_entities: Array<{
+        public_id: string;
+        code: string;
+        name: string;
+        is_direct: boolean;
+    }>;
+    joined_at: string | null;
+    left_at: string | null;
+}
+export interface LegalEntityMembersResponse {
+    data: LegalEntityMemberListItem[];
+    legal_entity: {
+        public_id: string;
+        code: string;
+        name: string;
+    };
+}
+export interface LegalEntityMemberListParams {
+    search?: string;
+    sort?: string;
+    perPage?: number;
+}
+export type LegalEntityMemberQueryResult = UseQueryResult<LegalEntityMembersResponse, Error>;
+export interface AttachmentUploader {
+    id: string | number;
+    public_id?: string | null;
+    name: string | null;
+    email: string | null;
+    display_label?: string;
+}
+/**
+ * Domain attachment UI vocabulary backed directly by one Media Library row.
+ * There is no Attachment model, endpoint, or second public identifier.
+ */
+export interface AttachmentItem {
+    id: number;
+    public_id: string;
+    original_name: string;
+    display_label?: string;
+    mime_type: string | null;
+    size_bytes: number;
+    scan_status?: string | null;
+    download_count: number;
+    last_downloaded_at: string | null;
+    download_url?: string;
+    created_at: string | null;
+    updated_at: string | null;
+    uploader?: AttachmentUploader | null;
+}
+/** Host-owned media returned after an App uploads a user-selected file. */
+export interface MediaItem {
+    id: number;
+    public_id: string;
+    display_label?: string;
+    original_name: string;
+    mime_type: string | null;
+    size_bytes: number;
+    scan_status?: string | null;
+    download_count: number;
+    last_downloaded_at: string | null;
+    download_url?: string;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface AttachmentsResponse {
+    data: AttachmentItem[];
+    meta: {
+        current_page: number;
+        last_page: number;
+        per_page: number;
+        total: number;
+        list_schema?: ResourceListSchema;
+    };
+}
+export interface AttachmentMutationResponse {
+    media: AttachmentItem;
+}
+export type AttachmentQueryResult = UseQueryResult<AttachmentsResponse, Error>;
+/** A closed host upload purpose for an attachment owner. */
+export interface AttachmentUploadOptions {
+    purpose?: 'media' | 'protected_attachment_pdf';
+}
+export type AttachmentUploadResult = UseMutationResult<AttachmentMutationResponse, Error, File>;
+export type AttachmentDeleteResult = UseMutationResult<void, Error, string | number>;
+export type MediaUploadResult = UseMutationResult<MediaItem, Error, File>;
+/** A browser transfer is driven by a host-issued, transport-neutral upload intent. */
+export interface UploadFileInput {
+    purpose: string;
+    file: File;
+    checksum?: string;
+    /**
+     * A closed upload-purpose target, validated and canonicalized by the
+     * host before bytes enter staging. App code never supplies a disk or path.
+     */
+    target?: Record<string, string | number | boolean | null>;
+    onProgress?: (progress: UploadProgress) => void;
+}
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+    percent: number | null;
+}
+export interface UploadIntent {
+    id: string;
+    purpose: string;
+    state: string;
+    transport?: 'direct' | 'proxy';
+    expires_at: string | null;
+    media?: unknown;
+}
+export interface UploadIntentResponse {
+    upload: UploadIntent;
+}
+export interface UploadTask {
+    result: Promise<UploadIntentResponse>;
+    cancel: () => void;
+    retry: () => UploadTask;
+}
+export interface WaitForUploadCompletionOptions {
+    /** Maximum number of authoritative status reads before timing out. */
+    attempts?: number;
+    /** Delay between status reads. */
+    intervalMs?: number;
+}
+export interface UploadFileClient {
+    uploadFile: (input: UploadFileInput) => UploadTask;
+    /** Waits for the host's asynchronous validation and materialization gates. */
+    waitForCompletion: (intentId: string, options?: WaitForUploadCompletionOptions) => Promise<UploadIntent>;
+}
+/** App-neutral metadata for a host-governed asset. Binary content stays in the host. */
+export interface TrustedAssetListItem {
+    kind: string;
+    public_id: string;
+    version: number;
+    label: string;
+    status: string;
+    valid_from: string | null;
+    valid_until: string | null;
+    metadata: Record<string, string | number | boolean | null>;
+}
+export interface TrustedAssetsResponse {
+    data: TrustedAssetListItem[];
+}
+export interface TrustedAssetListParams {
+    bindingKey: string;
+    bindingVersion: string;
+    kind: string;
+}
+export type TrustedAssetsQueryResult = UseQueryResult<TrustedAssetsResponse, Error>;
+export type PartyType = 'person' | 'organization';
+export type PartyStatus = 'active' | 'archived' | 'inactive';
+export interface PartyListItem {
+    id: number;
+    public_id: string;
+    display_label: string;
+    type: PartyType;
+    display_name: string;
+    legal_name: string | null;
+    business_number: string | null;
+    contact_email: string | null;
+    status: PartyStatus;
+    party_roles?: Array<{
+        id: number;
+        public_id: string;
+        role_code: string;
+        display_name: string | null;
+        owning_app: string | null;
+        granted_at: string | null;
+    }>;
+}
+export interface PartiesResponse {
+    parties: PartyListItem[];
+    meta?: {
+        current_page: number;
+        last_page: number;
+        per_page: number;
+        total: number;
+        list_schema?: ResourceListSchema;
+    };
+}
+export type PartyQueryResult = UseQueryResult<PartiesResponse, Error>;
+export interface PartyListParams extends Record<string, unknown> {
+    search?: string;
+    filters?: Record<string, string | string[]>;
+    sort?: string;
+    page?: number;
+    perPage?: number;
+}
+export interface ProfileSlotPropsV1 {
+    slotApiVersion: 1;
+    tenant: Pick<TenantContext, 'id' | 'name'>;
+    legalEntity: Pick<LegalEntityContext, 'name' | 'code' | 'public_id'> | null;
+    visibility: 'owner';
+    descriptorKey: string;
+    appKey: string;
+    familyKey: string;
+}
+export interface SelfWorkContext {
+    ref: string;
+    label: string;
+    description: string | null;
+    status: string | null;
+    effectiveFrom: string | null;
+    effectiveUntil: string | null;
+    isPrimary: boolean;
+}
+export interface ProfileSlotPropsV2 {
+    slotApiVersion: 2;
+    tenant: Pick<TenantContext, 'id' | 'name'>;
+    legalEntity: Pick<LegalEntityContext, 'name' | 'code' | 'public_id'> | null;
+    visibility: 'owner';
+    descriptorKey: string;
+    appKey: string;
+    familyKey: string;
+    workContext: SelfWorkContext | null;
+}
+export interface OperatingUnitScopeReference {
+    public_id: string;
+    code: string;
+    label: string;
+}
+export interface OperatingUnitScopeResult {
+    units: OperatingUnitScopeReference[];
+    selected: OperatingUnitScopeReference | null;
+    selectedId: string | null;
+    select: (publicId: string) => void;
+    isLoading: boolean;
+    isError: boolean;
+}
+export interface OperatingUnitScopeFieldProps {
+    scope: OperatingUnitScopeResult;
+}
+export interface ComponentSpec {
+    component: string;
+    props: Record<string, unknown>;
+    children: ComponentSpec[];
+    events: Record<string, {
+        tool: string;
+        payload: Record<string, unknown>;
+    }>;
+}
+export type AgentScope = Record<string, unknown>;
+export interface AgentComponentRendererProps {
+    spec: ComponentSpec;
+    scope: AgentScope;
+    preview?: boolean;
+    renderChild: (child: ComponentSpec, childScope: AgentScope) => ReactElement | null;
+}
+export type AgentComponentRenderer = ComponentType<AgentComponentRendererProps>;
+export interface ToolDataEnvelope {
+    tool: string;
+    data: unknown;
+    fetched_at: string;
+}
+export interface NxBarChartSeries {
+    key: string;
+    label: string;
+    color: string;
+}
+/**
+ * Series count above which a line chart reads as noise. Fold the tail into
+ * an Other bucket rather than passing more.
+ */
+export declare const NX_LINE_CHART_MAX_SERIES = 6;
+/** Segments beyond this are folded into one neutral "Other" slice. */
+export declare const NX_DONUT_MAX_SEGMENTS = 5;
+export interface NxDonutSegment {
+    key: string;
+    label: string;
+    value: number;
+    color: string;
+}
+export declare const queryKeys: {
+    profileSelfProjection: (tenantId: string, legalEntityPublicId: string | null, appKey: string, familyKey: string, workContextRef?: string | null) => readonly ["profile-self", string, string | null, "projection", string, string, string | null];
+    agentToolData: (tool: string | undefined, tenantId: string, legalEntityPublicId: string | null, argsKey: string) => readonly ["agent-tool-data", string | undefined, string, string | null, string];
+};
+export declare function withOperatingUnit(path: string, operatingUnitPublicId: string | null): string;
+export declare function parseRefreshHint(hint: string | undefined): number;
+export declare function resolveTokens(value: unknown, scope: AgentScope): unknown;
+/** Transport-neutral subset exposed by errors returned through the host API client. */
+export interface HttpError {
+    isAxiosError: true;
+    response?: {
+        status?: number;
+        data?: unknown;
+    };
+}
+export declare function isHttpError(error: unknown): error is HttpError;
+export declare function isAuthorityRevocationError(error: unknown): boolean;
+export declare function chartCategoricalColor(index: number): string;
+export type DashboardWidgetAutoHeightRef = RefCallback<HTMLElement>;

package/dist/platform.js

@@ -0,0 +1,114 @@
+/**
+ * Series count above which a line chart reads as noise. Fold the tail into
+ * an Other bucket rather than passing more.
+ */
+export const NX_LINE_CHART_MAX_SERIES = 6;
+/** Segments beyond this are folded into one neutral "Other" slice. */
+export const NX_DONUT_MAX_SEGMENTS = 5;
+export const queryKeys = {
+    profileSelfProjection: (tenantId, legalEntityPublicId, appKey, familyKey, workContextRef = null) => [
+        'profile-self',
+        tenantId,
+        legalEntityPublicId,
+        'projection',
+        appKey,
+        familyKey,
+        workContextRef,
+    ],
+    agentToolData: (tool, tenantId, legalEntityPublicId, argsKey) => [
+        'agent-tool-data',
+        tool,
+        tenantId,
+        legalEntityPublicId,
+        argsKey,
+    ],
+};
+export function withOperatingUnit(path, operatingUnitPublicId) {
+    if (!operatingUnitPublicId)
+        return path;
+    const separator = path.includes('?') ? '&' : '?';
+    return `${path}${separator}operating_unit=${encodeURIComponent(operatingUnitPublicId)}`;
+}
+const DEFAULT_REFRESH_MS = 60_000;
+const MIN_REFRESH_MS = 5_000;
+export function parseRefreshHint(hint) {
+    if (!hint)
+        return DEFAULT_REFRESH_MS;
+    const match = /^(\d+)\s*(ms|s|m)?$/.exec(hint.trim());
+    if (!match)
+        return DEFAULT_REFRESH_MS;
+    const value = Number(match[1]);
+    if (!Number.isFinite(value) || value <= 0)
+        return DEFAULT_REFRESH_MS;
+    const unit = match[2] ?? 's';
+    const milliseconds = unit === 'ms'
+        ? value
+        : unit === 'm'
+            ? value * 60_000
+            : value * 1_000;
+    return Math.max(MIN_REFRESH_MS, milliseconds);
+}
+export function resolveTokens(value, scope) {
+    if (typeof value === 'string') {
+        const pure = value.match(/^\$\{([^}]+)\}$/);
+        if (pure)
+            return resolveTokenPath(pure[1].trim(), scope) ?? '';
+        return value.replace(/\$\{([^}]+)\}/g, (_match, path) => {
+            const resolved = resolveTokenPath(path.trim(), scope);
+            return typeof resolved === 'string'
+                || typeof resolved === 'number'
+                || typeof resolved === 'boolean'
+                ? String(resolved)
+                : '';
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => resolveTokens(entry, scope));
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            resolveTokens(entry, scope),
+        ]));
+    }
+    return value;
+}
+function resolveTokenPath(path, scope) {
+    if (path === '')
+        return undefined;
+    return path.split('.').reduce((current, segment) => {
+        if (!isPlainObject(current))
+            return undefined;
+        return current[segment];
+    }, scope);
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || prototype === Object.prototype;
+}
+export function isHttpError(error) {
+    return error !== null
+        && typeof error === 'object'
+        && 'response' in error;
+}
+export function isAuthorityRevocationError(error) {
+    if (!isHttpError(error))
+        return false;
+    return [401, 403, 404].includes(error.response?.status ?? 0);
+}
+const CHART_CATEGORICAL_FALLBACK = [
+    '#3987e5',
+    '#199e70',
+    '#c98500',
+    '#008300',
+    '#9085e9',
+    '#e66767',
+    '#d55181',
+    '#d95926',
+];
+export function chartCategoricalColor(index) {
+    const slot = index % CHART_CATEGORICAL_FALLBACK.length;
+    return `var(--nx-chart-${slot + 1}, ${CHART_CATEGORICAL_FALLBACK[slot]})`;
+}

package/dist/process.d.ts

@@ -0,0 +1,98 @@
+import type { ComponentType, LazyExoticComponent } from 'react';
+export type BpmnEditorNodeType = 'startEvent' | 'endEvent' | 'userTask' | 'serviceTask' | 'sendTask' | 'receiveTask' | 'businessRuleTask' | 'exclusiveGateway' | 'parallelGateway' | 'inclusiveGateway' | 'intermediateTimerCatchEvent' | 'intermediateMessageCatchEvent' | 'boundaryTimerEvent' | 'boundaryErrorEvent' | 'subProcess' | 'callActivity' | 'sequenceFlow';
+export interface BpmnEditorElement {
+    id: string;
+    type: BpmnEditorNodeType;
+    name?: string;
+    sourceRef?: string;
+    targetRef?: string;
+    extensionElements?: {
+        nexia?: Record<string, unknown>;
+    };
+    flowElements?: BpmnEditorElement[];
+}
+export interface BpmnEditorProcess {
+    id: string;
+    name?: string;
+    isExecutable: boolean;
+    flowElements: BpmnEditorElement[];
+}
+export interface BpmnEditorDocument {
+    definitions: {
+        id?: string;
+        name?: string;
+        targetNamespace?: string;
+        processes: BpmnEditorProcess[];
+    };
+}
+export declare const DMN_EDITOR_HIT_POLICIES: readonly ["UNIQUE", "FIRST", "ANY", "COLLECT", "COLLECT_SUM", "COLLECT_MIN", "COLLECT_MAX", "COLLECT_COUNT"];
+export type DmnEditorHitPolicy = (typeof DMN_EDITOR_HIT_POLICIES)[number];
+export type DmnEditorValueType = 'string' | 'number' | 'boolean' | 'date' | 'dateTime' | 'duration' | 'list' | 'context';
+export interface DmnEditorInputClause {
+    id: string;
+    label?: string;
+    type?: DmnEditorValueType;
+}
+export interface DmnEditorOutputClause {
+    id: string;
+    label: string;
+    type: DmnEditorValueType;
+    purpose?: 'plain' | 'enum' | 'assignmentGroup';
+}
+export interface DmnEditorRule {
+    id: string;
+    when: Record<string, unknown>;
+    then: Record<string, unknown>;
+}
+export interface DmnEditorDocument {
+    inputs: DmnEditorInputClause[];
+    outputs: DmnEditorOutputClause[];
+    rules: DmnEditorRule[];
+    hitPolicy: DmnEditorHitPolicy;
+}
+/** Canonical resource anchor for the process instance hosting a UserTask. */
+export interface ProcessUserTaskResourceRef {
+    app_key: string;
+    resource_key: string;
+    resource_id: string;
+    resource_version?: string | null;
+}
+export interface ProcessUserTaskFormController {
+    /** Current widget validity; widgets re-register when this value changes. */
+    readonly canSubmit: boolean;
+    /** Build the App-owned input that Core forwards to the server-side handler. */
+    buildInput: () => Record<string, unknown>;
+}
+/** Versioned props for the closed `process.user_task.form` host slot. */
+export interface ProcessUserTaskFormSlotPropsV1 {
+    slotApiVersion: 1;
+    legalEntityPublicId: string;
+    task: {
+        id: number;
+        processInstancePublicId: string;
+        elementId: string;
+        taskKey: string;
+        stateVersion: number;
+    };
+    resourceRef: ProcessUserTaskResourceRef | null;
+    registerController: (controller: ProcessUserTaskFormController | null) => void;
+}
+export type ProcessUserTaskFormWidgetLoader = () => Promise<{
+    default: ComponentType<ProcessUserTaskFormSlotPropsV1>;
+}>;
+export interface ProcessUserTaskFormRegistration {
+    componentKey: string;
+    loader: ProcessUserTaskFormWidgetLoader;
+}
+/** App-facing registration capability. Inspection remains host/test-only. */
+export interface ProcessUserTaskFormRegistrar {
+    register(registration: ProcessUserTaskFormRegistration): void;
+}
+export interface ProcessUserTaskFormRegistry {
+    register(registration: ProcessUserTaskFormRegistration): void;
+    get: (componentKey: string) => LazyExoticComponent<ComponentType<ProcessUserTaskFormSlotPropsV1>> | null;
+    keys: () => string[];
+    subscribe: (listener: () => void) => () => void;
+    snapshot: () => number;
+    resetForTests: () => void;
+}

package/dist/process.js

@@ -0,0 +1,10 @@
+export const DMN_EDITOR_HIT_POLICIES = [
+    'UNIQUE',
+    'FIRST',
+    'ANY',
+    'COLLECT',
+    'COLLECT_SUM',
+    'COLLECT_MIN',
+    'COLLECT_MAX',
+    'COLLECT_COUNT',
+];