@nexia/sdk 0.5.0

package/dist/app-availability.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical availability of a target App from one consumer's viewpoint.
+ *
+ * Mirrors the backend `Nexia\AppRuntime\AppAvailability` enum. App-level
+ * state — distinct from the per-record `ResourceReferenceStatus` and the
+ * per-request `HandoffResultState`. Consume the values as-is.
+ */
+export declare const APP_AVAILABILITY_STATES: readonly ["operational", "unavailable", "disabled", "unauthorized", "failed", "stale"];
+export type AppAvailabilityState = (typeof APP_AVAILABILITY_STATES)[number];
+export declare function isAppAvailabilityState(value: unknown): value is AppAvailabilityState;
+/**
+ * Manual fallback is legitimate only when the target App has never been
+ * installed. Disabled, failed, stale, and unauthorized Apps retain their own
+ * recovery paths and must not be silently replaced.
+ */
+export declare function permitsManualFallback(state: AppAvailabilityState): boolean;
+/** @deprecated Use permitsManualFallback to match the PHP contract. */
+export declare const allowsManualAppFallback: typeof permitsManualFallback;

package/dist/app-availability.js

@@ -0,0 +1,29 @@
+/**
+ * Canonical availability of a target App from one consumer's viewpoint.
+ *
+ * Mirrors the backend `Nexia\AppRuntime\AppAvailability` enum. App-level
+ * state — distinct from the per-record `ResourceReferenceStatus` and the
+ * per-request `HandoffResultState`. Consume the values as-is.
+ */
+export const APP_AVAILABILITY_STATES = [
+    'operational',
+    'unavailable',
+    'disabled',
+    'unauthorized',
+    'failed',
+    'stale',
+];
+export function isAppAvailabilityState(value) {
+    return (typeof value === 'string' &&
+        APP_AVAILABILITY_STATES.includes(value));
+}
+/**
+ * Manual fallback is legitimate only when the target App has never been
+ * installed. Disabled, failed, stale, and unauthorized Apps retain their own
+ * recovery paths and must not be silently replaced.
+ */
+export function permitsManualFallback(state) {
+    return state === 'unavailable';
+}
+/** @deprecated Use permitsManualFallback to match the PHP contract. */
+export const allowsManualAppFallback = permitsManualFallback;

package/dist/approval.d.ts

@@ -0,0 +1,180 @@
+import type { ComponentType, LazyExoticComponent } from 'react';
+export declare const APPROVAL_STATES: readonly ["draft", "submitted", "approved", "rejected", "recalled", "cancelled"];
+export type ApprovalState = (typeof APPROVAL_STATES)[number];
+export type ApprovalBusinessFormEntryMode = 'create' | 'link';
+export declare const APPROVAL_STEP_KINDS: readonly ["approval", "consultation"];
+export type ApprovalStepKind = (typeof APPROVAL_STEP_KINDS)[number];
+export type ApprovalLineResolutionCategory = 'resolution' | 'authority' | 'availability';
+export interface ApprovalLineStep {
+    kind: ApprovalStepKind;
+    user_id: number;
+    is_final_authority?: boolean;
+}
+export type ApprovalLineStages = ApprovalLineStep[][];
+export interface ApprovalLineResolutionError {
+    code: string;
+    category: ApprovalLineResolutionCategory;
+    message: string;
+    user_id: number | null;
+}
+export interface ApprovalBusinessFormSubmitError {
+    kind: 'business_validation' | 'approval_line' | 'system';
+    message?: string;
+    lineErrors?: ApprovalLineResolutionError[];
+}
+export interface ApprovalActor {
+    id: number;
+    name: string;
+    email: string;
+    status: string;
+}
+export interface ApprovalStep {
+    id: number;
+    position: number;
+    branch_index: number;
+    kind: string;
+    mode: string;
+    state: string;
+    is_final_authority?: boolean;
+    required_user: ApprovalActor | null;
+    effective_actor: ApprovalActor | null;
+    acted_at: string | null;
+}
+export interface ApprovalBodySnapshot {
+    template_key: string;
+    template_version: number;
+    body: string;
+}
+export interface ApprovalSupplementalBodySnapshot {
+    body: string;
+}
+export interface ApprovalResourceSummaryField {
+    key: string;
+    type: string;
+    label_key?: string | null;
+    enum_labels?: Record<string, string> | null;
+    role?: 'subtitle' | 'meta' | 'status' | null;
+    value: unknown;
+}
+export interface ApprovalResourceSummary {
+    display: string;
+    route: string | null;
+    fields: ApprovalResourceSummaryField[];
+}
+export interface ApprovalDocumentField {
+    key: string;
+    type: string;
+    label_key?: string | null;
+    value?: unknown;
+    enum_labels?: Record<string, string> | null;
+    columns?: ApprovalDocumentField[];
+    rows?: Record<string, unknown>[];
+}
+export interface ApprovalDocumentSection {
+    title_key?: string | null;
+    fields: ApprovalDocumentField[];
+}
+export interface ApprovalDocument {
+    title_key?: string | null;
+    sections: ApprovalDocumentSection[];
+}
+export interface ApprovalDrafterIdentity {
+    name: string;
+    legal_entity_name: string;
+    affiliation?: string | null;
+    title?: string | null;
+    identifier?: string | null;
+}
+export interface ApprovalCirculationRecipient {
+    user: ApprovalActor | null;
+    acknowledged_at: string | null;
+}
+export interface ApprovalCase {
+    id: string;
+    legal_entity_public_id: string;
+    title: string;
+    document_number?: string | null;
+    state: ApprovalState;
+    drafter: ApprovalActor | null;
+    submitted_at: string | null;
+    drafter_identity?: ApprovalDrafterIdentity | null;
+    document?: ApprovalDocument | null;
+    resource_summary?: ApprovalResourceSummary | null;
+    submit_body_snapshot?: ApprovalBodySnapshot | null;
+    final_body_snapshot?: ApprovalBodySnapshot | null;
+    supplemental_body_snapshot?: ApprovalSupplementalBodySnapshot | null;
+    steps?: ApprovalStep[];
+    reference_recipients?: ApprovalActor[];
+    circulation_recipients?: ApprovalCirculationRecipient[];
+}
+export type ApprovalDocumentView = Pick<ApprovalCase, 'title' | 'document_number' | 'submitted_at' | 'drafter_identity' | 'drafter' | 'document' | 'supplemental_body_snapshot' | 'submit_body_snapshot' | 'final_body_snapshot' | 'resource_summary' | 'steps' | 'reference_recipients' | 'circulation_recipients'>;
+export interface ApprovalBusinessFormSubmitEnvelope {
+    templateKey: string;
+    templateVersion: number;
+    supplementalBody: string | null;
+    supportingAttachmentStageIds: string[];
+    line: ApprovalLineStages;
+    /** Provenance of the line as last confirmed in the Core composer. */
+    lineSource: 'manual' | 'personal_preset' | 'shared_line';
+    /** Shared route-policy key when lineSource is shared_line. */
+    lineSourceKey: string | null;
+    /** Canonical Core preview hash when lineSource is shared_line. */
+    lineSourceHash: string | null;
+    referenceUserIds: number[];
+    circulationUserIds: number[];
+}
+export interface ApprovalBusinessFormController {
+    readonly canSubmit: boolean;
+    saveDraft: () => Promise<ApprovalBusinessFormDraftResult>;
+    buildPreview: () => ApprovalDocumentView | null;
+    submit: (envelope: ApprovalBusinessFormSubmitEnvelope) => Promise<ApprovalBusinessFormSubmitResult>;
+}
+export interface ApprovalBusinessFormDraftResult {
+    appDraftRef: string;
+}
+export interface ApprovalBusinessFormSubmitResult {
+    caseId: string;
+}
+export interface ApprovalBusinessFormTemplate {
+    key: string;
+    version: number;
+}
+export interface ApprovalBusinessFormBinding {
+    key: string;
+    version: string | null;
+    entryMode: ApprovalBusinessFormEntryMode;
+}
+export interface ApprovalBusinessFormSubject {
+    resourceId: string;
+    resourceVersion: string | null;
+}
+export interface ApprovalBusinessFormSlotPropsV2 {
+    slotApiVersion: 2;
+    legalEntityPublicId: string;
+    template: ApprovalBusinessFormTemplate;
+    binding: ApprovalBusinessFormBinding;
+    subject?: ApprovalBusinessFormSubject;
+    appDraftRef?: string | null;
+    registerController: (controller: ApprovalBusinessFormController | null) => void;
+}
+export type ApprovalBusinessFormWidgetLoader = () => Promise<{
+    default: ComponentType<ApprovalBusinessFormSlotPropsV2>;
+}>;
+export interface ApprovalBusinessFormRegistration {
+    formWidgetKey: string;
+    loader: ApprovalBusinessFormWidgetLoader;
+}
+/** App-facing registration capability. Inspection remains host/test-only. */
+export interface ApprovalBusinessFormRegistrar {
+    register(registration: ApprovalBusinessFormRegistration): void;
+    register(formWidgetKey: string, loader: ApprovalBusinessFormWidgetLoader): void;
+}
+export interface ApprovalBusinessFormRegistry {
+    register(registration: ApprovalBusinessFormRegistration): void;
+    register(formWidgetKey: string, loader: ApprovalBusinessFormWidgetLoader): void;
+    get: (formWidgetKey: string) => LazyExoticComponent<ComponentType<ApprovalBusinessFormSlotPropsV2>> | null;
+    keys: () => string[];
+    subscribe: (listener: () => void) => () => void;
+    snapshot: () => number;
+    resetForTests: () => void;
+}

package/dist/approval.js

@@ -0,0 +1,9 @@
+export const APPROVAL_STATES = [
+    'draft',
+    'submitted',
+    'approved',
+    'rejected',
+    'recalled',
+    'cancelled',
+];
+export const APPROVAL_STEP_KINDS = ['approval', 'consultation'];

package/dist/context.d.ts

@@ -0,0 +1,49 @@
+import type { UseQueryResult } from '@tanstack/react-query';
+import type { SubjectPopulation } from './permissions';
+export interface UserContext {
+    id: number;
+    name: string;
+    email: string;
+    locale: string;
+    theme: string;
+    timezone: string;
+    table_style?: 'striped' | 'grid';
+    table_density?: 'compact' | 'standard' | 'comfortable';
+    must_reset_password: boolean;
+    must_enroll_two_factor: boolean;
+}
+export interface TenantContext {
+    id: string;
+    name: string;
+    symbol_url?: string | null;
+    default_business_timezone: string;
+}
+export interface LegalEntityContext {
+    public_id: string;
+    code: string;
+    name: string;
+}
+export interface WorkspaceContext {
+    id: number | string | null;
+    name: string | null;
+    slug: string | null;
+}
+export interface ContextResponse {
+    user: UserContext;
+    tenant: TenantContext | null;
+    /** @deprecated Shell bootstrap no longer emits a Legal Entity selection. */
+    legal_entity?: LegalEntityContext | null;
+    workspace: WorkspaceContext | null;
+    home?: {
+        default_dashboard_id: string | null;
+    } | null;
+}
+export interface PermissionsResponse {
+    permissions: string[];
+    permission_populations: Record<string, SubjectPopulation[]>;
+    roles: string[];
+    legal_entity_public_id?: string | null;
+    operating_unit_public_id?: string | null;
+}
+export type ContextQueryResult = UseQueryResult<ContextResponse>;
+export type PermissionsQueryResult = UseQueryResult<PermissionsResponse>;

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/data-migration.d.ts

@@ -0,0 +1,123 @@
+import type { ComponentType, LazyExoticComponent } from 'react';
+export type DataMigrationRunStatus = 'processing' | 'completed' | 'completed_with_errors' | 'failed';
+/** Host-owned asynchronous operation returned by migration analysis/apply APIs. */
+export interface DataMigrationBackgroundOperation<TResult = Readonly<Record<string, unknown>>> {
+    ticket: string;
+    status: 'processing' | 'completed' | 'failed' | 'unknown';
+    result?: TResult;
+    errors?: string[];
+    validation_errors?: Record<string, string[]>;
+    progress?: number;
+    phase?: string;
+}
+/** Initial response when a migration operation continues on the queue. */
+export interface DataMigrationOperationAccepted {
+    ticket: string;
+    status: 'processing';
+    status_url?: string;
+}
+export interface DataMigrationOperationWaitOptions {
+    statusUrl?: string;
+    signal?: AbortSignal;
+    onProgress?: (progress: number, phase: string | null) => void;
+}
+export interface DataMigrationBackgroundOperationClient {
+    wait<TResult>(accepted: DataMigrationOperationAccepted | string, options?: DataMigrationOperationWaitOptions): Promise<TResult>;
+    cancelAll(): void;
+}
+export declare function isDataMigrationOperationAccepted(value: unknown): value is DataMigrationOperationAccepted;
+/** Builds one browser file-picker contract from server-published format keys. */
+export declare function dataMigrationUploadAccept(formats: readonly string[]): string;
+export interface DataMigrationSessionCheckpointStore<TState> {
+    get(key: string): TState | null;
+    remember(key: string, state: TState): void;
+    delete(key: string): void;
+    clear(): void;
+}
+/**
+ * Bounded, session-memory-only checkpoints for migration surfaces that park or
+ * remount while a contextual Resource is created.
+ */
+export declare function createDataMigrationSessionCheckpointStore<TState>(capacity?: number): DataMigrationSessionCheckpointStore<TState>;
+/** Server-owned evidence for one concrete migration execution. */
+export interface DataMigrationRun {
+    public_id: string;
+    stage_key: string;
+    provider_key: string;
+    target_key: string;
+    status: DataMigrationRunStatus;
+    legal_entity_public_id: string | null;
+    result: Readonly<Record<string, unknown>> | null;
+    started_at: string;
+    completed_at: string | null;
+    failed_at: string | null;
+}
+/** Reads the standard terminal evidence embedded in migration API results. */
+export declare function dataMigrationRunPublicId(result: unknown): string | null;
+/**
+ * A stage only announces which server-owned run settled. The host re-reads
+ * that run from its authenticated API instead of trusting browser state as
+ * completion evidence.
+ */
+export interface DataMigrationStageCompletion {
+    runPublicId: string;
+}
+/** App-owned stage rendered inside the host-owned data migration workspace. */
+export interface DataMigrationStageProps {
+    providerKey: string;
+    onCompleted: (completion: DataMigrationStageCompletion) => void;
+}
+export type DataMigrationStageLoader = () => Promise<{
+    default: ComponentType<DataMigrationStageProps>;
+}>;
+export interface DataMigrationProviderRegistration {
+    key: string;
+    labelKey: string;
+    descriptionKey: string;
+    order: number;
+    ownerAppKey?: string | null;
+}
+/** Product destination shown in the host migration workspace. */
+export interface DataMigrationTargetRegistration {
+    key: string;
+    appFamilyKey: string;
+    familyOrder?: number;
+    labelKey: string;
+    descriptionKey: string;
+    order: number;
+    icon?: string | null;
+    /** App Catalog key when this target requires a tenant-installed App. */
+    installationAppKey?: string | null;
+    ownerAppKey?: string | null;
+}
+export interface DataMigrationStageRegistration {
+    /** Globally stable logical stage id shared by its provider adapters. */
+    id: string;
+    providerKey: string;
+    /** Logical destination; multiple providers may adapt the same stage. */
+    targetKey: string;
+    labelKey: string;
+    descriptionKey: string;
+    order: number;
+    ownerAppKey?: string | null;
+    requiredPermissions?: readonly string[];
+    permissionMode?: 'all' | 'any';
+    prerequisiteStageIds?: readonly string[];
+    loader: DataMigrationStageLoader;
+}
+/** App-facing capability. Inspection and composition remain host-owned. */
+export interface DataMigrationRegistrar {
+    registerProvider(registration: DataMigrationProviderRegistration): void;
+    registerTarget(registration: DataMigrationTargetRegistration): void;
+    registerStage(registration: DataMigrationStageRegistration): void;
+}
+export interface DataMigrationRegistry extends DataMigrationRegistrar {
+    providers(): readonly DataMigrationProviderRegistration[];
+    targets(): readonly DataMigrationTargetRegistration[];
+    allStages(): readonly DataMigrationStageRegistration[];
+    stages(providerKey: string): readonly DataMigrationStageRegistration[];
+    getStage(providerKey: string, stageId: string): LazyExoticComponent<ComponentType<DataMigrationStageProps>> | null;
+    subscribe(listener: () => void): () => void;
+    snapshot(): number;
+    resetForTests(): void;
+}

package/dist/data-migration.js

@@ -0,0 +1,70 @@
+export function isDataMigrationOperationAccepted(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && 'ticket' in value
+        && typeof value.ticket === 'string'
+        && value.status === 'processing');
+}
+const DATA_MIGRATION_FORMAT_ACCEPT = {
+    csv: ['.csv', 'text/csv'],
+    xlsx: [
+        '.xlsx',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ],
+    xlsm: [
+        '.xlsm',
+        'application/vnd.ms-excel.sheet.macroEnabled.12',
+    ],
+};
+/** Builds one browser file-picker contract from server-published format keys. */
+export function dataMigrationUploadAccept(formats) {
+    return Array.from(new Set(formats.flatMap((format) => {
+        const normalized = format.trim().toLowerCase();
+        if (!normalized)
+            return [];
+        return DATA_MIGRATION_FORMAT_ACCEPT[normalized] ?? [`.${normalized}`];
+    }))).join(',');
+}
+/**
+ * Bounded, session-memory-only checkpoints for migration surfaces that park or
+ * remount while a contextual Resource is created.
+ */
+export function createDataMigrationSessionCheckpointStore(capacity = 24) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+        throw new Error('Data migration checkpoint capacity must be positive.');
+    }
+    const states = new Map();
+    return {
+        get: (key) => states.get(key) ?? null,
+        remember(key, state) {
+            states.delete(key);
+            states.set(key, state);
+            while (states.size > capacity) {
+                const oldest = states.keys().next().value;
+                if (typeof oldest !== 'string')
+                    break;
+                states.delete(oldest);
+            }
+        },
+        delete: (key) => {
+            states.delete(key);
+        },
+        clear: () => states.clear(),
+    };
+}
+/** Reads the standard terminal evidence embedded in migration API results. */
+export function dataMigrationRunPublicId(result) {
+    if (typeof result !== 'object' || result === null || Array.isArray(result)) {
+        return null;
+    }
+    const migrationRun = result.migration_run;
+    if (typeof migrationRun !== 'object'
+        || migrationRun === null
+        || Array.isArray(migrationRun)) {
+        return null;
+    }
+    const publicId = migrationRun.public_id;
+    return typeof publicId === 'string' && publicId.trim() !== ''
+        ? publicId
+        : null;
+}

package/dist/fixtures/approval-contract-negative.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fixtures/approval-contract-negative.js

@@ -0,0 +1,8 @@
+const validRegistration = {
+    formWidgetKey: 'sample.expense_report',
+    loader: async () => ({ default: () => null }),
+};
+registry.register(validRegistration);
+// @ts-expect-error A registrar payload must supply its typed widget loader.
+registry.register({ formWidgetKey: 'sample.expense_report' });
+export {};

package/dist/handoff-result.d.ts

@@ -0,0 +1,6 @@
+export declare const HANDOFF_RESULT_STATES: readonly ["ACCEPTED", "REJECTED", "UNAUTHORIZED", "STALE", "RETRYABLE_FAILED", "TERMINAL_FAILED"];
+export type HandoffResultState = (typeof HANDOFF_RESULT_STATES)[number];
+export declare function isHandoffResultState(value: unknown): value is HandoffResultState;
+export declare function isRetryableFailure(state: HandoffResultState): boolean;
+/** @deprecated Use isRetryableFailure to match the PHP contract. */
+export declare const isRetryableHandoffFailure: typeof isRetryableFailure;

package/dist/handoff-result.js

@@ -0,0 +1,17 @@
+export const HANDOFF_RESULT_STATES = [
+    'ACCEPTED',
+    'REJECTED',
+    'UNAUTHORIZED',
+    'STALE',
+    'RETRYABLE_FAILED',
+    'TERMINAL_FAILED',
+];
+export function isHandoffResultState(value) {
+    return (typeof value === 'string' &&
+        HANDOFF_RESULT_STATES.includes(value));
+}
+export function isRetryableFailure(state) {
+    return state === 'RETRYABLE_FAILED';
+}
+/** @deprecated Use isRetryableFailure to match the PHP contract. */
+export const isRetryableHandoffFailure = isRetryableFailure;