@nexia/sdk 0.5.0

package/dist/resource-reference.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Canonical cross-app resource reference availability contract.
+ *
+ * Mirrors the backend `Nexia\ResourceReference\ReferenceStatus` enum. Apps
+ * must consume these values as-is — re-encoding a status (for example
+ * renaming `absent` to `unavailable`) breaks the shared vocabulary that the
+ * host and other Apps rely on.
+ *
+ * This is unrelated to the `WorkTabRef` inspector-stack UI handle exported
+ * from `shell.ts`; that type identifies an open work tab, not a cross-app
+ * resource reference.
+ */
+export declare const RESOURCE_REFERENCE_STATUSES: readonly ["available", "absent", "disabled", "failed", "stale", "unauthorized"];
+export type ResourceReferenceStatus = (typeof RESOURCE_REFERENCE_STATUSES)[number];
+export declare function isResourceReferenceStatus(value: unknown): value is ResourceReferenceStatus;
+/** Canonical `{app_key, resource_key, resource_id}` reference tuple. */
+export interface ResourceReferenceIdentity {
+    app_key: string;
+    resource_key: string;
+    resource_id: string;
+    display?: string;
+    href?: string | null;
+}
+/**
+ * Present an already-saved reference without treating its snapshot as a live
+ * owner-App link. Only an available reference may expose its stored href; all
+ * other states retain the saved display while remaining snapshot-only.
+ */
+export declare function savedResourceReferencePresentation(reference: ResourceReferenceIdentity, status: ResourceReferenceStatus): {
+    readonly display: string;
+    readonly href: string | null;
+    readonly liveRefreshAllowed: boolean;
+    readonly snapshotOnly: boolean;
+};
+/** PII-free signal emitted after an owning App has committed a resource projection. */
+export interface ResourceProjectionChangeSubscription {
+    tenantId: string | undefined;
+    resource: Pick<ResourceReferenceIdentity, 'app_key' | 'resource_key' | 'resource_id'>;
+    onChanged: () => void;
+    enabled?: boolean;
+}
+/** Availability of one referenced resource kind for the current actor. */
+export interface ResourceReferenceAvailability {
+    resource_key: string;
+    status: ResourceReferenceStatus;
+}
+/** One owner-authorized option returned by the host reference selector. */
+export interface ResourceReferenceOption {
+    reference: Required<ResourceReferenceIdentity>;
+    fields: Record<string, unknown>;
+    revision: number | null;
+    status: string | null;
+    as_of: string;
+}
+export interface ResourceReferenceOptionsResponse {
+    data: ResourceReferenceOption[];
+}
+export interface ResourceReferenceOptionPageMeta {
+    resource_key: string;
+    dependency_state: ResourceReferenceStatus;
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+}
+export interface ResourceReferenceOptionPage extends ResourceReferenceOptionsResponse {
+    meta: ResourceReferenceOptionPageMeta;
+}
+/** Validate the host selector response before an App renders owner data. */
+export declare function parseResourceReferenceOptionPage(value: unknown, expectedResourceKey: string): ResourceReferenceOptionPage;
+/** Resource picker data may stay fresh briefly without another network read. */
+export declare const RESOURCE_PICKER_STALE_TIME_MS = 5000;
+export interface ResourcePickerRefetchOptions {
+    cancelRefetch?: boolean;
+}
+/** Minimal TanStack-compatible state consumed by the host combobox contract. */
+export interface ResourcePickerQueryState {
+    isStale: boolean;
+    isFetching: boolean;
+    refetch: (options?: ResourcePickerRefetchOptions) => unknown;
+}
+export interface ResourcePickerRevalidationOptions {
+    /** Bypass the freshness window for an explicit user refresh. */
+    force?: boolean;
+}
+export type ResourcePickerRevalidation = (options?: ResourcePickerRevalidationOptions) => unknown;
+/** Adapt a query result without exposing TanStack Query types through the SDK. */
+export declare function resourcePickerRevalidation(query: ResourcePickerQueryState): ResourcePickerRevalidation;
+export interface ResourceReferencePickerQueryScope {
+    resourceKey: string;
+    tenantId: string | number | null | undefined;
+    legalEntityPublicId?: string | null;
+}
+export interface ResourceReferenceSelectorContext {
+    consumerResourceKey: string;
+    consumerField: string;
+}
+/** Stable prefix invalidated after any successful mutation of the owner Resource. */
+export declare function resourceReferencePickerQueryRoot({ resourceKey, tenantId, legalEntityPublicId, }: ResourceReferencePickerQueryScope): readonly ["resource-reference-picker", string, string | number | null, string | null];
+/** Exact picker key; purpose and dependencies prevent incompatible cache shapes. */
+export declare function resourceReferencePickerQueryKey(scope: ResourceReferencePickerQueryScope & {
+    purpose?: string;
+    dependencies?: readonly unknown[];
+}): readonly ["resource-reference-picker", string, string | number | null, string | null, string, ...unknown[]];
+/**
+ * Canonical host route for cross-App selectors. `null` is an explicit
+ * tenant-scoped context, never a request to infer a Legal Entity or Shell state.
+ */
+export declare function resourceReferenceOptionsRoute(legalEntityPublicId: string | null, resourceKey: string, selector: ResourceReferenceSelectorContext): string;
+/**
+ * A referenced target blocks dependent work when it exists but cannot be
+ * used right now (disabled, failed, stale, or unauthorized). `absent` is not blocking:
+ * the target App is simply not part of this tenant.
+ */
+export declare function isResourceReferenceBlocked(status: ResourceReferenceStatus): boolean;
+/**
+ * Manual fallback (free-text entry, exclusion, or local substitute) is only
+ * legitimate when the target App is absent from the tenant. Unauthorized or
+ * failing references must surface their own recovery path instead of being
+ * silently replaced.
+ */
+export declare function allowsManualReferenceFallback(status: ResourceReferenceStatus): boolean;

package/dist/resource-reference.js

@@ -0,0 +1,203 @@
+/**
+ * Canonical cross-app resource reference availability contract.
+ *
+ * Mirrors the backend `Nexia\ResourceReference\ReferenceStatus` enum. Apps
+ * must consume these values as-is — re-encoding a status (for example
+ * renaming `absent` to `unavailable`) breaks the shared vocabulary that the
+ * host and other Apps rely on.
+ *
+ * This is unrelated to the `WorkTabRef` inspector-stack UI handle exported
+ * from `shell.ts`; that type identifies an open work tab, not a cross-app
+ * resource reference.
+ */
+export const RESOURCE_REFERENCE_STATUSES = [
+    'available',
+    'absent',
+    'disabled',
+    'failed',
+    'stale',
+    'unauthorized',
+];
+export function isResourceReferenceStatus(value) {
+    return (typeof value === 'string' &&
+        RESOURCE_REFERENCE_STATUSES.includes(value));
+}
+/**
+ * Present an already-saved reference without treating its snapshot as a live
+ * owner-App link. Only an available reference may expose its stored href; all
+ * other states retain the saved display while remaining snapshot-only.
+ */
+export function savedResourceReferencePresentation(reference, status) {
+    const display = typeof reference.display === 'string' && reference.display.trim() !== ''
+        ? reference.display
+        : reference.resource_id;
+    const available = status === 'available';
+    return {
+        display,
+        href: available && reference.href ? reference.href : null,
+        liveRefreshAllowed: available,
+        snapshotOnly: !available,
+    };
+}
+const RESOURCE_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*\.[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
+/** Validate the host selector response before an App renders owner data. */
+export function parseResourceReferenceOptionPage(value, expectedResourceKey) {
+    if (expectedResourceKey.length > 160 || !RESOURCE_KEY_PATTERN.test(expectedResourceKey)) {
+        throw new Error('Expected Resource Reference key is invalid.');
+    }
+    const root = referenceObject(value, 'response');
+    const meta = referenceObject(root.meta, 'meta');
+    const resourceKey = referenceString(meta.resource_key, 'meta.resource_key');
+    if (resourceKey !== expectedResourceKey) {
+        throw new Error(`ResourceReference response key mismatch: expected ${expectedResourceKey}.`);
+    }
+    const dependencyState = referenceString(meta.dependency_state, 'meta.dependency_state');
+    if (!isResourceReferenceStatus(dependencyState)) {
+        throw new Error('ResourceReference dependency_state is invalid.');
+    }
+    const data = referenceArray(root.data, 'data').map((item, index) => {
+        const option = referenceObject(item, `data.${index}`);
+        const reference = referenceObject(option.reference, `data.${index}.reference`);
+        const appKey = referenceString(reference.app_key, `data.${index}.reference.app_key`);
+        const optionResourceKey = referenceString(reference.resource_key, `data.${index}.reference.resource_key`);
+        if (optionResourceKey !== expectedResourceKey ||
+            optionResourceKey.split('.', 1)[0] !== appKey) {
+            throw new Error('ResourceReference option ownership is contradictory.');
+        }
+        const resourceId = referenceString(reference.resource_id, `data.${index}.reference.resource_id`);
+        if (resourceId !== resourceId.trim() || [...resourceId].length > 255) {
+            throw new Error(`data.${index}.reference.resource_id is invalid.`);
+        }
+        const href = reference.href;
+        if (href !== null && typeof href !== 'string') {
+            throw new Error(`data.${index}.reference.href must be a string or null.`);
+        }
+        const revision = option.revision;
+        if (revision !== null &&
+            (!Number.isSafeInteger(revision) || Number(revision) < 0)) {
+            throw new Error(`data.${index}.revision must be a non-negative integer or null.`);
+        }
+        const status = option.status;
+        if (status !== null && typeof status !== 'string') {
+            throw new Error(`data.${index}.status must be a string or null.`);
+        }
+        return {
+            reference: {
+                app_key: appKey,
+                resource_key: optionResourceKey,
+                resource_id: resourceId,
+                display: referenceString(reference.display, `data.${index}.reference.display`),
+                href,
+            },
+            fields: referenceObject(option.fields, `data.${index}.fields`),
+            revision: revision === null ? null : Number(revision),
+            status,
+            as_of: referenceString(option.as_of, `data.${index}.as_of`),
+        };
+    });
+    if (dependencyState !== 'available' && data.length > 0) {
+        throw new Error('Non-available ResourceReference responses must not expose records.');
+    }
+    const currentPage = referenceInteger(meta.current_page, 'meta.current_page', 1);
+    const lastPage = referenceInteger(meta.last_page, 'meta.last_page', 1);
+    const perPage = referenceInteger(meta.per_page, 'meta.per_page', 1);
+    const total = referenceInteger(meta.total, 'meta.total', 0);
+    if (lastPage !== Math.max(1, Math.ceil(total / perPage)) ||
+        data.length > perPage ||
+        data.length > total ||
+        (currentPage > lastPage && data.length > 0)) {
+        throw new Error('ResourceReference pagination metadata is contradictory.');
+    }
+    return {
+        data,
+        meta: {
+            resource_key: resourceKey,
+            dependency_state: dependencyState,
+            current_page: currentPage,
+            last_page: lastPage,
+            per_page: perPage,
+            total,
+        },
+    };
+}
+/** Resource picker data may stay fresh briefly without another network read. */
+export const RESOURCE_PICKER_STALE_TIME_MS = 5_000;
+/** Adapt a query result without exposing TanStack Query types through the SDK. */
+export function resourcePickerRevalidation(query) {
+    return (options = {}) => {
+        if ((!options.force && !query.isStale) || query.isFetching)
+            return;
+        return query.refetch({ cancelRefetch: false });
+    };
+}
+/** Stable prefix invalidated after any successful mutation of the owner Resource. */
+export function resourceReferencePickerQueryRoot({ resourceKey, tenantId, legalEntityPublicId = null, }) {
+    return [
+        'resource-reference-picker',
+        resourceKey,
+        tenantId ?? null,
+        legalEntityPublicId,
+    ];
+}
+/** Exact picker key; purpose and dependencies prevent incompatible cache shapes. */
+export function resourceReferencePickerQueryKey(scope) {
+    return [
+        ...resourceReferencePickerQueryRoot(scope),
+        scope.purpose ?? 'default',
+        ...(scope.dependencies ?? []),
+    ];
+}
+/**
+ * Canonical host route for cross-App selectors. `null` is an explicit
+ * tenant-scoped context, never a request to infer a Legal Entity or Shell state.
+ */
+export function resourceReferenceOptionsRoute(legalEntityPublicId, resourceKey, selector) {
+    const route = legalEntityPublicId === null
+        ? `/resource-references/${encodeURIComponent(resourceKey)}/options`
+        : `/legal-entities/${encodeURIComponent(legalEntityPublicId)}/resource-references/${encodeURIComponent(resourceKey)}/options`;
+    const query = new URLSearchParams({
+        consumer_resource_key: selector.consumerResourceKey,
+        consumer_field: selector.consumerField,
+    });
+    return `${route}?${query.toString()}`;
+}
+/**
+ * A referenced target blocks dependent work when it exists but cannot be
+ * used right now (disabled, failed, stale, or unauthorized). `absent` is not blocking:
+ * the target App is simply not part of this tenant.
+ */
+export function isResourceReferenceBlocked(status) {
+    return status !== 'available' && status !== 'absent';
+}
+/**
+ * Manual fallback (free-text entry, exclusion, or local substitute) is only
+ * legitimate when the target App is absent from the tenant. Unauthorized or
+ * failing references must surface their own recovery path instead of being
+ * silently replaced.
+ */
+export function allowsManualReferenceFallback(status) {
+    return status === 'absent';
+}
+function referenceObject(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${path} must be an object.`);
+    }
+    return value;
+}
+function referenceArray(value, path) {
+    if (!Array.isArray(value))
+        throw new Error(`${path} must be an array.`);
+    return value;
+}
+function referenceString(value, path) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${path} must be a non-empty string.`);
+    }
+    return value;
+}
+function referenceInteger(value, path, minimum) {
+    if (!Number.isSafeInteger(value) || Number(value) < minimum) {
+        throw new Error(`${path} must be an integer greater than or equal to ${minimum}.`);
+    }
+    return Number(value);
+}

package/dist/resources/resource-information.d.ts

@@ -0,0 +1,128 @@
+import type { ReactNode } from "react";
+import type { OrganizationTargetSelectorOption } from "../organization-target";
+/** Surface-owned, authorized form target. Never a page/list scope. */
+export type ResourceFormLegalEntity = {
+    kind: "select";
+    value: string | null;
+    options: readonly OrganizationTargetSelectorOption[];
+    onChange: (value: string) => void;
+    disabled?: boolean;
+    error?: ReactNode;
+} | {
+    kind: "stored";
+    /** Human label from the record or a read-authorized lookup of its owner. */
+    label: ReactNode;
+};
+/** Why a field matters to the Resource lifecycle. */
+export type ResourceInformationRequirement = "save" | "readiness" | "optional";
+/** The projections in which a field occupies its canonical position. */
+export type ResourceInformationMode = "view" | "create" | "edit";
+/** Responsive width hint for the Form projection. View always uses detail rows. */
+export type ResourceInformationFieldSpan = "half" | "full";
+export interface ResourceInformationValue {
+    value: ReactNode;
+    empty?: boolean;
+    mono?: boolean;
+}
+export interface ResourceInformationControlSlot {
+    id: string;
+    describedBy?: string;
+    invalid: boolean;
+}
+export interface ResourceInformationEditRenderContext<TContext> {
+    mode: "create" | "edit";
+    context: TContext;
+}
+export interface ResourceInformationControlProjection<TContext> {
+    kind: "control";
+    render: (context: ResourceInformationEditRenderContext<TContext>, slot: ResourceInformationControlSlot) => ReactNode;
+    error?: (context: ResourceInformationEditRenderContext<TContext>) => ReactNode;
+}
+export interface ResourceInformationReadOnlyProjection<TContext> {
+    kind: "read-only";
+    render: (context: ResourceInformationEditRenderContext<TContext>) => ResourceInformationValue;
+}
+/**
+ * Escape hatch for a composite field such as an address editor. The field
+ * still has one canonical schema position and one View value, while the App
+ * owns the compound Edit control.
+ */
+export interface ResourceInformationCustomProjection<TContext> {
+    kind: "custom";
+    render: (context: ResourceInformationEditRenderContext<TContext>) => ReactNode;
+}
+export type ResourceInformationEditProjection<TContext> = ResourceInformationControlProjection<TContext> | ResourceInformationReadOnlyProjection<TContext> | ResourceInformationCustomProjection<TContext>;
+export interface ResourceInformationField<TViewContext, TEditContext> {
+    key: string;
+    labelKey: string;
+    /** Persistent entry guidance rendered below an Edit control. */
+    helpKey?: string;
+    /** Short domain definition rendered from the field label. */
+    definitionKey?: string;
+    requirement?: ResourceInformationRequirement;
+    span?: ResourceInformationFieldSpan;
+    /** Defaults to all projections. Omissions must be deliberate and explicit. */
+    modes?: readonly ResourceInformationMode[];
+    /** Context-dependent visibility evaluated after the static mode contract. */
+    visibility?: {
+        view?: (context: TViewContext) => boolean;
+        create?: (context: TEditContext) => boolean;
+        edit?: (context: TEditContext) => boolean;
+    };
+    view: (context: TViewContext) => ResourceInformationValue;
+    edit: ResourceInformationEditProjection<TEditContext>;
+}
+export interface ResourceInformationSection<TViewContext, TEditContext> {
+    key: string;
+    titleKey: string;
+    descriptionKey?: string;
+    /** Form layout only. View remains an ordered, compact definition list. */
+    formColumns?: 1 | 2;
+    /** Optional aggregate or projection owner, for example `resource` or `party`. */
+    source?: string;
+    fields: readonly ResourceInformationField<TViewContext, TEditContext>[];
+}
+/**
+ * One ordered Resource information contract projected by both View and Edit.
+ * Route loading, mutations, and related-resource actions remain Surface-owned.
+ */
+export interface ResourceInformationSchema<TViewContext, TEditContext> {
+    sections: readonly ResourceInformationSection<TViewContext, TEditContext>[];
+}
+export interface ResourceInformationTranslator {
+    (key: string): string;
+}
+export interface NxResourceInformationViewProps<TViewContext, TEditContext = never> {
+    schema: ResourceInformationSchema<TViewContext, TEditContext>;
+    context: TViewContext;
+    translate: ResourceInformationTranslator;
+    emptyValue: ReactNode;
+    visibleEmptyRequirements?: readonly ResourceInformationRequirement[];
+    testIdPrefix?: string;
+}
+/** Place inside the first input section of a custom form. */
+export interface NxResourceFormLegalEntityFieldProps {
+    target: ResourceFormLegalEntity;
+    mode: "create" | "edit";
+}
+export interface NxResourceInformationFormProps<TViewContext, TEditContext> {
+    schema: ResourceInformationSchema<TViewContext, TEditContext>;
+    context: TEditContext;
+    mode: "create" | "edit";
+    /** First field of the first schema section, full row width. Omit for tenant-owned forms.
+     * Use `stored` on edit; the host never renders an editable owner in edit mode.
+     * Do not also declare the Legal Entity field in the form schema.
+     */
+    legalEntity?: ResourceFormLegalEntity;
+    translate: ResourceInformationTranslator;
+    emptyValue: ReactNode;
+    testIdPrefix?: string;
+}
+/**
+ * Checks a schema once, then deliberately widens it to the stable host
+ * contract. Keeping every App field as one deep literal union makes a
+ * workspace-wide typecheck retain the complete product catalog in memory.
+ */
+export declare function defineResourceInformationSchema<TViewContext, TEditContext>(): (schema: ResourceInformationSchema<TViewContext, TEditContext>) => ResourceInformationSchema<TViewContext, TEditContext>;
+/** Explicit value helper so an empty string is never mistaken for a value. */
+export declare function resourceInformationValue(value: ReactNode, options?: Omit<ResourceInformationValue, "value">): ResourceInformationValue;

package/dist/resources/resource-information.js

@@ -0,0 +1,12 @@
+/**
+ * Checks a schema once, then deliberately widens it to the stable host
+ * contract. Keeping every App field as one deep literal union makes a
+ * workspace-wide typecheck retain the complete product catalog in memory.
+ */
+export function defineResourceInformationSchema() {
+    return (schema) => schema;
+}
+/** Explicit value helper so an empty string is never mistaken for a value. */
+export function resourceInformationValue(value, options = {}) {
+    return { value, ...options };
+}

package/dist/resources/resource-list.d.ts

@@ -0,0 +1,23 @@
+/** A filter definition published by a resource list endpoint. */
+export interface ResourceListFilterableEntry {
+    key: string;
+    multiple: boolean;
+    label: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+}
+/**
+ * Self-describing list schema published as `meta.list_schema`.
+ *
+ * Apps and the host shell share this wire contract so list chrome can render
+ * filtering, sorting, and search without a resource-specific schema mirror.
+ */
+export interface ResourceListSchema {
+    /** Canonical record key for host capabilities that refresh this list. */
+    resource_key?: string;
+    sortable: string[];
+    filterable: ResourceListFilterableEntry[];
+    searchable: string[];
+}

package/dist/resources/resource-list.js

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