nucleus-core-ts 0.9.821 → 0.9.822

package/dist/fe/components/IntegrationsPage/components/ConnectionList.js

@@ -5,6 +5,7 @@ import { cn } from '../../../utils/cn';
 import { useIntegrationsStore } from '../store';
 import { useLabels } from '../text/context';
 import { integrationsPageTheme } from '../theme';
+import { ConnectionTransfer } from './ConnectionTransfer';
 import { Badge, Field, Notice } from './Primitives';
 import { ListSkeleton } from './Skeletons';
 import { useInfiniteList } from './useInfiniteList';
@@ -105,6 +106,10 @@ export function ConnectionList({ actions, onNewConnection, reloadToken = 0 }) {
                     })
                 ]
             }),
+            /*#__PURE__*/ _jsx(ConnectionTransfer, {
+                actions: actions,
+                onImported: list.reload
+            }),
             /*#__PURE__*/ _jsx(Field, {
                 htmlFor: "connection-search",
                 label: labels.connections.searchLabel,

package/dist/fe/components/IntegrationsPage/components/ConnectionTransfer.d.ts

@@ -0,0 +1,7 @@
+import type { IntegrationsActions } from '../types';
+export type ConnectionTransferProps = {
+    actions: IntegrationsActions;
+    /** Bumped by the caller so the rail refetches after a file is brought in. */
+    onImported?: () => void;
+};
+export declare function ConnectionTransfer({ actions, onImported }: ConnectionTransferProps): import("react/jsx-runtime").JSX.Element;

package/dist/fe/components/IntegrationsPage/components/ConnectionTransfer.js

@@ -0,0 +1,157 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { useIntegrationsStore } from '../store';
+import { integrationsPageTheme } from '../theme';
+import { Notice } from './Primitives';
+/**
+ * Taking a whole integration somewhere else, and bringing one back.
+ *
+ * A connection is the connection, the calls it makes, the parameters those calls
+ * take from each other, and the mappings that turn the answers into rows.
+ * Rebuilding that by hand in a second environment is hours of work and a fresh
+ * chance to get one field wrong in a way nobody notices until an import writes
+ * it. So it travels as one file.
+ *
+ * The file carries NO credentials — deliberately, and it says so on both sides,
+ * because a connection that arrives looking configured and cannot authenticate
+ * is a confusing half hour otherwise.
+ */ const theme = integrationsPageTheme;
+const messageOf = (error)=>error instanceof Error ? error.message : 'The request failed.';
+/** A filename somebody can still recognise a week later. */ const fileNameFor = (slug)=>`integration-${slug || 'connection'}.json`;
+export function ConnectionTransfer({ actions, onImported }) {
+    const store = useIntegrationsStore();
+    const fileRef = useRef(null);
+    const [busy, setBusy] = useState(false);
+    const [problems, setProblems] = useState([]);
+    const [note, setNote] = useState(null);
+    const selected = store.sources.find((source)=>source.id === store.selectedSourceId);
+    const exportOne = ()=>{
+        if (!selected) return;
+        setBusy(true);
+        setProblems([]);
+        setNote(null);
+        actions.exportConnection(selected.id).then((document)=>{
+            setBusy(false);
+            if (!document) {
+                store.setError('The connection could not be exported.');
+                return;
+            }
+            // Written from the browser rather than served as a download, so the file
+            // never travels back through a URL somebody could share by accident.
+            const blob = new Blob([
+                JSON.stringify(document, null, 2)
+            ], {
+                type: 'application/json'
+            });
+            const url = URL.createObjectURL(blob);
+            const link = window.document.createElement('a');
+            link.href = url;
+            link.download = fileNameFor(selected.slug);
+            link.click();
+            URL.revokeObjectURL(url);
+            setNote('Exported. Credentials are not in the file — enter them wherever it lands.');
+        }).catch((error)=>{
+            setBusy(false);
+            store.setError(messageOf(error));
+        });
+    };
+    const importFile = (file)=>{
+        setBusy(true);
+        setProblems([]);
+        setNote(null);
+        file.text().then((text)=>{
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            } catch  {
+                setBusy(false);
+                setProblems([
+                    {
+                        path: file.name,
+                        message: 'This file is not readable as JSON.'
+                    }
+                ]);
+                return;
+            }
+            return actions.importConnection(parsed).then((result)=>{
+                setBusy(false);
+                if (!result.ok) {
+                    setProblems(result.problems ?? [
+                        {
+                            path: '',
+                            message: result.message
+                        }
+                    ]);
+                    return;
+                }
+                setNote(result.message);
+                onImported?.();
+            });
+        }).catch((error)=>{
+            setBusy(false);
+            store.setError(messageOf(error));
+        });
+    };
+    return /*#__PURE__*/ _jsxs("section", {
+        className: "flex flex-col gap-2",
+        children: [
+            /*#__PURE__*/ _jsxs("div", {
+                className: "flex flex-wrap gap-2",
+                children: [
+                    /*#__PURE__*/ _jsx("button", {
+                        className: theme.button.secondary,
+                        disabled: busy || !selected,
+                        onClick: exportOne,
+                        title: selected ? `Export ${selected.name} — its calls and mappings, without any credential` : 'Choose a connection to export',
+                        type: "button",
+                        children: busy ? 'Working…' : 'Export'
+                    }),
+                    /*#__PURE__*/ _jsx("button", {
+                        className: theme.button.secondary,
+                        disabled: busy,
+                        onClick: ()=>fileRef.current?.click(),
+                        type: "button",
+                        children: "Import"
+                    }),
+                    /*#__PURE__*/ _jsx("input", {
+                        accept: "application/json,.json",
+                        className: "hidden",
+                        onChange: (event)=>{
+                            const file = event.target.files?.[0];
+                            // Cleared so choosing the same file twice fires again — the second
+                            // attempt is usually the one after fixing something.
+                            event.target.value = '';
+                            if (file) importFile(file);
+                        },
+                        ref: fileRef,
+                        type: "file"
+                    })
+                ]
+            }),
+            note ? /*#__PURE__*/ _jsx("p", {
+                className: theme.field.hint,
+                children: note
+            }) : null,
+            problems.length > 0 ? /*#__PURE__*/ _jsx(Notice, {
+                title: "This file cannot be imported as it stands",
+                tone: "danger",
+                children: /*#__PURE__*/ _jsx("ul", {
+                    className: "flex flex-col gap-1",
+                    children: problems.map((problem)=>/*#__PURE__*/ _jsxs("li", {
+                            className: theme.field.hint,
+                            children: [
+                                problem.path ? /*#__PURE__*/ _jsxs("strong", {
+                                    children: [
+                                        problem.path,
+                                        ": "
+                                    ]
+                                }) : null,
+                                problem.message
+                            ]
+                        }, `${problem.path}-${problem.message}`))
+                })
+            }) : null
+        ]
+    });
+}

package/dist/fe/components/IntegrationsPage/components/RunPanel.js

@@ -8,6 +8,7 @@ import { Notice } from './Primitives';
 import { RunConfirmStep } from './RunConfirmStep';
 import { MIN_SHARED_PASSWORD, RunPasswordField } from './RunPasswordField';
 import { RunPlanReferences } from './RunPlanReferences';
+import { RunPlanSuggestions } from './RunPlanSuggestions';
 import { RunPlanSummary } from './RunPlanSummary';
 import { RunProgressBar } from './RunProgressBar';
 import { describeLosses, errorText } from './runFormat';
@@ -207,6 +208,11 @@ export function RunPanel({ mapping, actions, onSubscribeProgress, onRunSettled }
                             /*#__PURE__*/ _jsx(RunPlanSummary, {
                                 plan: plan
                             }),
+                            /*#__PURE__*/ _jsx(RunPlanSuggestions, {
+                                mapping: mapping,
+                                onEditMapping: ()=>store.setTab('mappings'),
+                                plan: plan
+                            }),
                             /*#__PURE__*/ _jsx(RunPlanReferences, {
                                 busy: starting || activeRunId !== null || !passwordReady,
                                 onCreateAndRun: ()=>start(false, 'create'),

package/dist/fe/components/IntegrationsPage/components/RunPlanSuggestions.d.ts

@@ -0,0 +1,15 @@
+import type { IntegrationMapping, RunPlanValue } from '../types';
+/** `{name}.{surname}@example.com`, built from what this source really sends. */
+export declare function suggestEmailTemplate(mapping: IntegrationMapping): string | null;
+/** How many records each required field kept out, largest first. */
+export declare function missingRequiredCounts(plan: RunPlanValue): {
+    field: string;
+    records: number;
+}[];
+export type RunPlanSuggestionsProps = {
+    plan: RunPlanValue;
+    mapping: IntegrationMapping;
+    /** Takes the operator to the mapping, where the fix is made. */
+    onEditMapping?: () => void;
+};
+export declare function RunPlanSuggestions({ plan, mapping, onEditMapping }: RunPlanSuggestionsProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/fe/components/IntegrationsPage/components/RunPlanSuggestions.js

@@ -0,0 +1,120 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { integrationsPageTheme } from '../theme';
+import { Notice } from './Primitives';
+/**
+ * What to DO about the records this import would leave out.
+ *
+ * A preview that says "561 records are missing e-mail" has told the truth and
+ * stopped one step short of being useful: the answer is nearly always to build
+ * the value from the fields that ARE there, and the panel knows which those are.
+ * Leaving the operator to work that out — and to guess that Fallback takes
+ * `{braces}` at all — is how a capability that exists goes unused.
+ *
+ * So the suggestion is written out, with the record's own field names in it,
+ * ready to be copied into the mapping.
+ */ const theme = integrationsPageTheme;
+/** Column names that plausibly hold an address, so the advice can be specific. */ const EMAIL_LIKE = /mail/i;
+/** Source fields that plausibly name a person, in the order they read best. */ const GIVEN_NAME = /^(name|first|firstname|given|ad)$/i;
+const FAMILY_NAME = /^(surname|last|lastname|family|soyad)$/i;
+/** Fields the source actually sends, from what the mapping already reads. */ function sourceFieldsOf(mapping) {
+    return (Array.isArray(mapping.fieldMappings) ? mapping.fieldMappings : []).map((row)=>row.source).filter((source)=>source.trim() !== '' && !source.includes('{'));
+}
+/** `{name}.{surname}@example.com`, built from what this source really sends. */ export function suggestEmailTemplate(mapping) {
+    const fields = sourceFieldsOf(mapping);
+    const given = fields.find((field)=>GIVEN_NAME.test(field));
+    const family = fields.find((field)=>FAMILY_NAME.test(field));
+    if (!given && !family) return null;
+    const parts = [
+        given,
+        family
+    ].filter(Boolean).join('}.{');
+    return `{${parts}}@example.com`;
+}
+/** How many records each required field kept out, largest first. */ export function missingRequiredCounts(plan) {
+    const counts = new Map();
+    for (const issue of plan.issues){
+        if (issue.kind !== 'missing_required') continue;
+        // The field names are in the message the planner wrote; it is the only
+        // place they exist, and re-deriving them from the row would be a guess.
+        const named = issue.message.replace(/^Required field\(s\) empty:\s*/, '');
+        for (const field of named.split(',').map((part)=>part.trim())){
+            if (field) counts.set(field, (counts.get(field) ?? 0) + 1);
+        }
+    }
+    return [
+        ...counts.entries()
+    ].map(([field, records])=>({
+            field,
+            records
+        })).sort((a, b)=>b.records - a.records);
+}
+export function RunPlanSuggestions({ plan, mapping, onEditMapping }) {
+    const missing = missingRequiredCounts(plan);
+    if (missing.length === 0) return null;
+    const template = suggestEmailTemplate(mapping);
+    return /*#__PURE__*/ _jsx("section", {
+        className: "flex flex-col gap-3",
+        children: missing.map((entry)=>{
+            const isEmail = EMAIL_LIKE.test(entry.field);
+            return /*#__PURE__*/ _jsxs(Notice, {
+                title: `${entry.records} record(s) have no ${entry.field}, so they are left out`,
+                tone: "warning",
+                children: [
+                    isEmail && template ? /*#__PURE__*/ _jsxs(_Fragment, {
+                        children: [
+                            /*#__PURE__*/ _jsxs("p", {
+                                children: [
+                                    "An address can be built from the fields the source DOES send. On the mapping, set",
+                                    ' ',
+                                    /*#__PURE__*/ _jsx("strong", {
+                                        children: "Fallback"
+                                    }),
+                                    " on the ",
+                                    /*#__PURE__*/ _jsx("strong", {
+                                        children: entry.field
+                                    }),
+                                    " row to something like:"
+                                ]
+                            }),
+                            /*#__PURE__*/ _jsx("p", {
+                                className: "mt-1",
+                                children: /*#__PURE__*/ _jsx("code", {
+                                    className: theme.code,
+                                    children: template
+                                })
+                            }),
+                            /*#__PURE__*/ _jsxs("p", {
+                                className: "mt-1",
+                                children: [
+                                    "Pair it with the ",
+                                    /*#__PURE__*/ _jsx("strong", {
+                                        children: "E-mail safe"
+                                    }),
+                                    " transform and ",
+                                    /*#__PURE__*/ _jsx("em", {
+                                        children: "Ayşe Yılmaz"
+                                    }),
+                                    ' ',
+                                    "becomes ",
+                                    /*#__PURE__*/ _jsx("em", {
+                                        children: "ayse.yilmaz@example.com"
+                                    }),
+                                    ". Records that already carry an address keep the one they have — the fallback is only used when the source is empty."
+                                ]
+                            })
+                        ]
+                    }) : /*#__PURE__*/ _jsx("p", {
+                        children: `Nothing in this import fills ${entry.field}, and the table will not accept a row without it. Either map a source field to it, or give that row a Fallback — a fixed value, or one built from other fields with {braces}.`
+                    }),
+                    onEditMapping ? /*#__PURE__*/ _jsx("button", {
+                        className: `${theme.button.secondary} mt-3`,
+                        onClick: onEditMapping,
+                        type: "button",
+                        children: "Open the mapping"
+                    }) : null
+                ]
+            }, entry.field);
+        })
+    });
+}

package/dist/fe/components/IntegrationsPage/components/RunPlanSuggestions.test.d.ts

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

package/dist/fe/components/IntegrationsPage/components/RunPlanSuggestions.test.js

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'bun:test';
+import { missingRequiredCounts, suggestEmailTemplate } from './RunPlanSuggestions';
+/**
+ * A preview that says "561 records are missing e-mail" has told the truth and
+ * stopped one step short of being useful. The answer is nearly always to build
+ * the value from the fields that ARE there, and the panel knows which those are.
+ */ const plan = (issues)=>({
+        issues,
+        referenceInserts: [],
+        warnings: []
+    });
+const issue = (message, i)=>({
+        sourceIndex: i,
+        kind: 'missing_required',
+        message
+    });
+describe('counting what each missing field costs', ()=>{
+    it('counts the records one field kept out', ()=>{
+        const counts = missingRequiredCounts(plan([
+            issue('Required field(s) empty: email', 0),
+            issue('Required field(s) empty: email', 1)
+        ]));
+        expect(counts).toEqual([
+            {
+                field: 'email',
+                records: 2
+            }
+        ]);
+    });
+    it('counts each field of a record that is missing two', ()=>{
+        const counts = missingRequiredCounts(plan([
+            issue('Required field(s) empty: email, code', 0)
+        ]));
+        expect(counts).toEqual([
+            {
+                field: 'email',
+                records: 1
+            },
+            {
+                field: 'code',
+                records: 1
+            }
+        ]);
+    });
+    it('puts the biggest problem first', ()=>{
+        const counts = missingRequiredCounts(plan([
+            issue('Required field(s) empty: code', 0),
+            issue('Required field(s) empty: email', 1),
+            issue('Required field(s) empty: email', 2)
+        ]));
+        expect(counts[0]).toEqual({
+            field: 'email',
+            records: 2
+        });
+    });
+    it('ignores issues of every other kind', ()=>{
+        const counts = missingRequiredCounts(plan([
+            {
+                sourceIndex: 0,
+                kind: 'duplicate_in_batch',
+                message: 'twice'
+            }
+        ]));
+        expect(counts).toEqual([]);
+    });
+});
+describe('the address it suggests building', ()=>{
+    const mapping = (sources)=>({
+            fieldMappings: sources.map((source)=>({
+                    source,
+                    target: source
+                }))
+        });
+    it('is built from the fields this source really sends', ()=>{
+        expect(suggestEmailTemplate(mapping([
+            'name',
+            'surname',
+            'employeeNo'
+        ]))).toBe('{name}.{surname}@example.com');
+    });
+    it('recognises the other names those fields go by', ()=>{
+        expect(suggestEmailTemplate(mapping([
+            'firstName',
+            'lastName'
+        ]))).toBe('{firstName}.{lastName}@example.com');
+    });
+    it('offers what it can when only one of the two is there', ()=>{
+        expect(suggestEmailTemplate(mapping([
+            'surname'
+        ]))).toBe('{surname}@example.com');
+    });
+    it('suggests nothing rather than nonsense when there is no name at all', ()=>{
+        expect(suggestEmailTemplate(mapping([
+            'employeeNo',
+            'departmentCode'
+        ]))).toBeNull();
+    });
+    it('ignores a source that is already a template', ()=>{
+        expect(suggestEmailTemplate(mapping([
+            '{a}-{b}'
+        ]))).toBeNull();
+    });
+});

package/dist/fe/components/IntegrationsPage/components/fieldMappingOptions.js

@@ -26,7 +26,8 @@ export const TRANSFORMS = [
     'toBoolean',
     'dateOnly',
     'emailSafe',
-    'pathLeaf'
+    'pathLeaf',
+    'toList'
 ];
 export const TRANSFORM_LABEL = {
     none: 'No transform',
@@ -38,7 +39,8 @@ export const TRANSFORM_LABEL = {
     toBoolean: 'To boolean',
     dateOnly: 'Date only',
     emailSafe: 'E-mail safe (ascii, lowercase)',
-    pathLeaf: 'Last part of a path (A/B/C → C)'
+    pathLeaf: 'Last part of a path (A/B/C → C)',
+    toList: 'To a list (for a column that holds many)'
 };
 /** Narrows what a select reported back to a transform this panel knows. */ export function toTransform(value) {
     return TRANSFORMS.find((option)=>option === value) ?? 'none';

package/dist/fe/components/IntegrationsPage/index.d.ts

@@ -1,11 +1,13 @@
 export { ConnectionList } from './components/ConnectionList';
 export type { ConnectionTabsProps } from './components/ConnectionTabs';
 export { ConnectionTabs, connectionTabId, connectionTabPanelId } from './components/ConnectionTabs';
+export { ConnectionTransfer } from './components/ConnectionTransfer';
 export { EndpointsTab } from './components/EndpointsTab';
 export { IntegrationsPage } from './components/IntegrationsPage';
 export { MappingsTab } from './components/MappingsTab';
 export type { BadgeProps, BadgeTone, CodeBlockProps, FieldProps, NoticeProps, NoticeTone, StatProps, } from './components/Primitives';
 export { Badge, CodeBlock, Field, Notice, Stat } from './components/Primitives';
+export { RunPlanSuggestions } from './components/RunPlanSuggestions';
 export { RunsTab } from './components/RunsTab';
 export type { ListSkeletonProps } from './components/Skeletons';
 export { CardSkeleton, ListSkeleton, StatGridSkeleton } from './components/Skeletons';

package/dist/fe/components/IntegrationsPage/index.js

@@ -1,9 +1,11 @@
 export { ConnectionList } from './components/ConnectionList';
 export { ConnectionTabs, connectionTabId, connectionTabPanelId } from './components/ConnectionTabs';
+export { ConnectionTransfer } from './components/ConnectionTransfer';
 export { EndpointsTab } from './components/EndpointsTab';
 export { IntegrationsPage } from './components/IntegrationsPage';
 export { MappingsTab } from './components/MappingsTab';
 export { Badge, CodeBlock, Field, Notice, Stat } from './components/Primitives';
+export { RunPlanSuggestions } from './components/RunPlanSuggestions';
 export { RunsTab } from './components/RunsTab';
 export { CardSkeleton, ListSkeleton, StatGridSkeleton } from './components/Skeletons';
 export { useInfiniteList } from './components/useInfiniteList';

package/dist/fe/components/IntegrationsPage/types/actions.d.ts

@@ -92,6 +92,24 @@ export type IntegrationsActions = {
         label: string;
         fields: string[];
     }[]>;
+    /**
+     * The whole connection as one portable document — WITHOUT any credential.
+     *
+     * A connection is the connection, its calls, the parameters those calls take
+     * from each other and the mappings that turn the answers into rows. Moving
+     * that by hand between environments is hours of work and a fresh chance to
+     * get one field wrong in a way nobody notices until an import writes it.
+     */
+    exportConnection: (sourceId: string) => Promise<unknown>;
+    /** Brings such a document in. Re-importing the same file updates rather than duplicates. */
+    importConnection: (document: unknown) => Promise<{
+        ok: boolean;
+        message: string;
+        problems?: {
+            path: string;
+            message: string;
+        }[];
+    }>;
 };
 export type IntegrationsPageProps = {
     title?: string;

package/dist/fe/components/IntegrationsPage/types/records.d.ts

@@ -86,7 +86,7 @@ export type IntegrationEndpoint = {
     } | null;
     enabled?: boolean;
 };
-export type MappingTransformValue = 'none' | 'trim' | 'upper' | 'lower' | 'toString' | 'toNumber' | 'toBoolean' | 'dateOnly' | 'emailSafe' | 'pathLeaf';
+export type MappingTransformValue = 'none' | 'trim' | 'upper' | 'lower' | 'toString' | 'toNumber' | 'toBoolean' | 'dateOnly' | 'emailSafe' | 'pathLeaf' | 'toList';
 export type FieldMappingValue = {
     source: string;
     target: string;