Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.
import type { Kysely, KyselyDatabase, KyselyTx } from "@carbon/database/client";
import { getCompanyGroupId } from "./account-mapping";
import type { ExternalIntegrationMapping } from "./external-mapping";
import { createMappingService } from "./external-mapping";
import type { PostingSyncDimensionSlot } from "./models";
import type { JournalLineDimensionRef } from "./posting";
import type { DimensionTarget } from "./types";
/**
* Dimension-value mapping service: thin wrappers over
* ExternalIntegrationMappingService with entityType = "dimensionValue",
* linking Carbon dimension VALUES to provider analytics options (QBO
* Class/Department entities, Xero tracking options, Rillet Field values).
*
* The Carbon side of a mapping is the composite `<dimensionId>:<valueId>`
* — valueId alone is polymorphic across entity-typed dimensions
* (location.id, supplier.id, item.id, dimensionValue.id, …), so the
* composite key is required. The provider side is the option id in
* `externalId`, with the display name in metadata — exactly like account
* mapping (core/account-mapping.ts).
*
* What crosses the wire to a provider is always the RESOLVED provider
* option id; Carbon's internal value ids never leave. Provider-side
* creation (autoCreate) is always BY NAME — the READABLE label resolved
* per the dimension's entityType (resolveDimensionValueLabels, mirroring
* DimensionSelector.tsx / getEntityValuesByIds in the accounting module).
*/
export const DIMENSION_VALUE_MAPPING_ENTITY_TYPE = "dimensionValue";
type Db = Kysely<KyselyDatabase> | KyselyTx;
/** `<dimensionId>:<valueId>` — the mapping row's entityId. */
export function buildDimensionValueMappingEntityId(
dimensionId: string,
valueId: string
): string {
return `${dimensionId}:${valueId}`;
}
/** Split a mapping entityId back into `{ dimensionId, valueId }` (null when malformed). */
export function parseDimensionValueMappingEntityId(
entityId: string
): JournalLineDimensionRef | null {
const separator = entityId.indexOf(":");
if (separator <= 0 || separator === entityId.length - 1) return null;
return {
dimensionId: entityId.slice(0, separator),
valueId: entityId.slice(separator + 1)
};
}
function toErrorMessage(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
/**
* A dimension-value mapping row shaped for display / lookup.
*/
export interface DimensionValueMapping {
id: string;
dimensionId: string;
valueId: string;
externalId: string | null;
externalName: string | null;
lastSyncedAt: string | null;
metadata: Record<string, unknown> | null;
}
/**
* A Carbon dimension value with its resolved READABLE label (part
* readable id for Item dimensions, name for everything else).
*/
export interface DimensionValueWithLabel extends JournalLineDimensionRef {
label: string | null;
}
/**
* A proposed (not written) match between a Carbon dimension value and a
* provider option. The UI confirms proposals and calls
* upsertDimensionValueMapping.
*/
export interface DimensionValueMatchProposal {
dimensionId: string;
valueId: string;
label: string;
externalId: string;
externalName: string | null;
}
function getExternalNameFromMetadata(metadata: unknown): string | null {
if (typeof metadata !== "object" || metadata === null) return null;
const { externalName } = metadata as Record<string, unknown>;
return typeof externalName === "string" ? externalName : null;
}
/**
* All dimension-value mappings for an integration (optionally one
* dimension), parsed out of the composite entityId. Malformed rows are
* skipped.
*/
export async function getDimensionValueMappings(
db: Db,
args: { companyId: string; integration: string; dimensionId?: string }
): Promise<{ data: DimensionValueMapping[] | null; error: string | null }> {
try {
const rows = await db
.selectFrom("externalIntegrationMapping")
.select(["id", "entityId", "externalId", "metadata", "lastSyncedAt"])
.where("entityType", "=", DIMENSION_VALUE_MAPPING_ENTITY_TYPE)
.where("integration", "=", args.integration)
.where("companyId", "=", args.companyId)
.execute();
const data: DimensionValueMapping[] = [];
for (const row of rows) {
const parsed = parseDimensionValueMappingEntityId(row.entityId);
if (!parsed) continue;
if (args.dimensionId && parsed.dimensionId !== args.dimensionId) {
continue;
}
data.push({
id: row.id,
dimensionId: parsed.dimensionId,
valueId: parsed.valueId,
externalId: row.externalId ?? null,
externalName: getExternalNameFromMetadata(row.metadata),
lastSyncedAt: (row.lastSyncedAt as string | null) ?? null,
metadata: (row.metadata as Record<string, unknown> | null) ?? null
});
}
return { data, error: null };
} catch (err) {
return { data: null, error: toErrorMessage(err) };
}
}
/**
* Lookup used by pre-flight and the provider mappers:
* `<dimensionId>:<valueId>` → provider option id. Mappings without a
* stored externalId count as unmapped.
*/
export function buildDimensionValueMappingLookup(
mappings: ReadonlyArray<DimensionValueMapping>
): Map<string, string> {
const lookup = new Map<string, string>();
for (const mapping of mappings) {
if (mapping.externalId) {
lookup.set(
buildDimensionValueMappingEntityId(
mapping.dimensionId,
mapping.valueId
),
mapping.externalId
);
}
}
return lookup;
}
/**
* The dimension when it belongs to the company's group, else null.
* Dimensions are company-group scoped.
*/
async function getGroupDimension(
db: Db,
args: { companyId: string; dimensionId: string }
): Promise<{ entityType: string; companyGroupId: string } | null> {
const companyGroupId = await getCompanyGroupId(db, args.companyId);
if (!companyGroupId) return null;
const dimension = await db
.selectFrom("dimension")
.select("entityType")
.where("id", "=", args.dimensionId)
.where("companyGroupId", "=", companyGroupId)
.executeTakeFirst();
return dimension
? { entityType: String(dimension.entityType), companyGroupId }
: null;
}
/**
* Does the value belong to the company's group? Custom values are
* group-scoped `dimensionValue` rows of this dimension; entity-typed values
* are company-scoped rows of the dimension's source table, accepted for any
* company in the group (and unowned rows with a null companyId). An entity
* type with no known source table is not checked.
*/
async function isGroupDimensionValue(
db: Db,
args: {
companyGroupId: string;
dimensionId: string;
entityType: string;
valueId: string;
}
): Promise<boolean> {
const { companyGroupId } = args;
if (args.entityType === "Custom") {
const value = await db
.selectFrom("dimensionValue")
.select("id")
.where("id", "=", args.valueId)
.where("dimensionId", "=", args.dimensionId)
.where("companyGroupId", "=", companyGroupId)
.executeTakeFirst();
return !!value;
}
const source = DIMENSION_LABEL_SOURCES[args.entityType];
if (!source) return true;
const rows = await (db as Kysely<KyselyDatabase>)
.selectFrom(source.table as never)
.select(`${source.table}.companyId` as never)
.where(`${source.table}.id` as never, "=" as never, args.valueId as never)
.execute();
if (rows.length === 0) return false;
const groupCompanies = await db
.selectFrom("company")
.select("id")
.where("companyGroupId", "=", companyGroupId)
.execute();
const inGroup = new Set(groupCompanies.map((company) => company.id));
return (rows as Array<Record<string, unknown>>).some((row) => {
const owner = row.companyId;
return owner === null || (typeof owner === "string" && inGroup.has(owner));
});
}
/**
* Upsert a dimension-value mapping (`<dimensionId>:<valueId>` → provider
* option id). Several Carbon values may legitimately share one provider
* option (consolidation), so duplicate external ids are allowed — the
* same stance as account mapping.
*/
export async function upsertDimensionValueMapping(
db: Db,
args: {
companyId: string;
integration: string;
dimensionId: string;
valueId: string;
externalId: string;
externalName?: string;
userId?: string;
}
): Promise<{ data: ExternalIntegrationMapping | null; error: string | null }> {
try {
// dimensionId/valueId can come from a form field, and this Kysely client
// bypasses RLS: refuse a dimension or value from outside the caller's
// group, whose label the mapping tab would otherwise resolve and show.
const dimension = await getGroupDimension(db, args);
if (!dimension) {
return { data: null, error: `Dimension ${args.dimensionId} not found` };
}
if (
!(await isGroupDimensionValue(db, {
...dimension,
dimensionId: args.dimensionId,
valueId: args.valueId
}))
) {
return {
data: null,
error: `Dimension value ${args.valueId} not found`
};
}
const mappingService = createMappingService(db, args.companyId);
const entityId = buildDimensionValueMappingEntityId(
args.dimensionId,
args.valueId
);
await mappingService.link(
DIMENSION_VALUE_MAPPING_ENTITY_TYPE,
entityId,
args.integration,
args.externalId,
{
...(args.externalName
? { metadata: { externalName: args.externalName } }
: {}),
...(args.userId ? { createdBy: args.userId } : {}),
allowDuplicateExternalId: true
}
);
const data = await mappingService.getByEntity(
DIMENSION_VALUE_MAPPING_ENTITY_TYPE,
entityId,
args.integration
);
return { data, error: null };
} catch (err) {
return { data: null, error: toErrorMessage(err) };
}
}
/**
* Dimension → provider FIELD mapping service (entityType "dimension"),
* mirroring the value service above. The Carbon side is the plain
* `dimensionId`; the provider side is the Field/dimension id in `externalId`
* (Rillet Field uuid). Used by the "send all dimensions" flow to auto-
* provision a provider Field per Carbon dimension, so a value mapping always
* has a Field to hang off of.
*/
export const DIMENSION_MAPPING_ENTITY_TYPE = "dimension";
/** A dimension → provider Field mapping row. */
export interface DimensionFieldMapping {
id: string;
dimensionId: string;
externalId: string | null;
externalName: string | null;
}
/** All dimension → provider Field mappings for an integration. */
export async function getDimensionMappings(
db: Db,
args: { companyId: string; integration: string }
): Promise<{ data: DimensionFieldMapping[] | null; error: string | null }> {
try {
const rows = await db
.selectFrom("externalIntegrationMapping")
.select(["id", "entityId", "externalId", "metadata"])
.where("entityType", "=", DIMENSION_MAPPING_ENTITY_TYPE)
.where("integration", "=", args.integration)
.where("companyId", "=", args.companyId)
.execute();
const data = rows.map((row) => ({
id: row.id,
dimensionId: row.entityId,
externalId: row.externalId ?? null,
externalName: getExternalNameFromMetadata(row.metadata)
}));
return { data, error: null };
} catch (err) {
return { data: null, error: toErrorMessage(err) };
}
}
/** `dimensionId` → provider Field id. Rows without an externalId are unmapped. */
export function buildDimensionFieldLookup(
mappings: ReadonlyArray<DimensionFieldMapping>
): Map<string, string> {
const lookup = new Map<string, string>();
for (const mapping of mappings) {
if (mapping.externalId) lookup.set(mapping.dimensionId, mapping.externalId);
}
return lookup;
}
/**
* Upsert a dimension → provider Field mapping (dimensionId → Field id). Two
* Carbon dimensions that share a name may resolve to one provider Field
* (auto-provision reuses an existing Field by name), so duplicate external
* ids are allowed — the same stance as the value + account mappings.
*/
export async function upsertDimensionMapping(
db: Db,
args: {
companyId: string;
integration: string;
dimensionId: string;
externalId: string;
externalName?: string;
userId?: string;
}
): Promise<{ data: ExternalIntegrationMapping | null; error: string | null }> {
try {
if (!(await getGroupDimension(db, args))) {
return { data: null, error: `Dimension ${args.dimensionId} not found` };
}
const mappingService = createMappingService(db, args.companyId);
await mappingService.link(
DIMENSION_MAPPING_ENTITY_TYPE,
args.dimensionId,
args.integration,
args.externalId,
{
...(args.externalName
? { metadata: { externalName: args.externalName } }
: {}),
...(args.userId ? { createdBy: args.userId } : {}),
allowDuplicateExternalId: true
}
);
const data = await mappingService.getByEntity(
DIMENSION_MAPPING_ENTITY_TYPE,
args.dimensionId,
args.integration
);
return { data, error: null };
} catch (err) {
return { data: null, error: toErrorMessage(err) };
}
}
/**
* `dimensionId` → dimension name, for auto-provisioning provider Fields by
* name. Queries `dimension` by id (already company-scoped by provenance —
* the ids come from the company's journal lines), mirroring how
* resolveDimensionValueLabels reads the dimension table.
*/
export async function loadDimensionNames(
db: Db,
args: { dimensionIds: ReadonlyArray<string> }
): Promise<Map<string, string>> {
const names = new Map<string, string>();
if (args.dimensionIds.length === 0) return names;
const rows = await db
.selectFrom("dimension")
.select(["id", "name"])
.where("id", "in", [...args.dimensionIds])
.execute();
for (const row of rows) {
if (typeof row.name === "string" && row.name) names.set(row.id, row.name);
}
return names;
}
/**
* Propose matches where a Carbon dimension value's resolved label equals
* a provider option name EXACTLY (no trimming, no case folding).
* Ambiguous candidates are skipped: duplicate labels among the values,
* duplicate names among the provider options, values already mapped, and
* provider options already used by a mapping. Pure — the UI confirms
* proposals and calls upsertDimensionValueMapping.
*/
export function matchDimensionValuesByName(args: {
values: ReadonlyArray<DimensionValueWithLabel>;
providerOptions: ReadonlyArray<{ id: string; name: string | null }>;
mappedValueKeys?: Iterable<string>;
mappedExternalIds?: Iterable<string>;
}): DimensionValueMatchProposal[] {
const mappedValueKeys = new Set(args.mappedValueKeys ?? []);
const mappedExternalIds = new Set(args.mappedExternalIds ?? []);
const optionsByName = new Map<string, { id: string; name: string }>();
const ambiguousNames = new Set<string>();
for (const option of args.providerOptions) {
if (!option.name) continue;
if (optionsByName.has(option.name)) {
ambiguousNames.add(option.name);
continue;
}
optionsByName.set(option.name, { id: option.id, name: option.name });
}
const labelCounts = new Map<string, number>();
for (const value of args.values) {
if (!value.label) continue;
labelCounts.set(value.label, (labelCounts.get(value.label) ?? 0) + 1);
}
const proposals: DimensionValueMatchProposal[] = [];
for (const value of args.values) {
if (!value.label) continue;
const key = buildDimensionValueMappingEntityId(
value.dimensionId,
value.valueId
);
if (mappedValueKeys.has(key)) continue;
if ((labelCounts.get(value.label) ?? 0) > 1) continue;
if (ambiguousNames.has(value.label)) continue;
const option = optionsByName.get(value.label);
if (!option) continue;
if (mappedExternalIds.has(option.id)) continue;
proposals.push({
dimensionId: value.dimensionId,
valueId: value.valueId,
label: value.label,
externalId: option.id,
externalName: option.name
});
}
return proposals;
}
// /********************************************************\
// * Label resolution (Carbon-side, readable) *
// \********************************************************/
/**
* The source table + label column per dimension entityType. Mirrors
* `getEntityValuesByIds` in apps/erp accounting.service.ts and the
* DimensionSelector's client-store resolution (WorkCenter/Process). The
* Item label is the READABLE part id (readableIdWithRevision), never the
* internal id.
*/
type LabelSource = { table: string; labelColumn: string };
const DIMENSION_LABEL_SOURCES: Record<string, LabelSource> = {
Custom: { table: "dimensionValue", labelColumn: "name" },
Location: { table: "location", labelColumn: "name" },
Department: { table: "department", labelColumn: "name" },
Employee: { table: "employeeSummary", labelColumn: "name" },
CustomerType: { table: "customerType", labelColumn: "name" },
SupplierType: { table: "supplierType", labelColumn: "name" },
ItemPostingGroup: { table: "itemPostingGroup", labelColumn: "name" },
CostCenter: { table: "costCenter", labelColumn: "name" },
FixedAssetClass: { table: "fixedAssetClass", labelColumn: "name" },
Customer: { table: "customer", labelColumn: "name" },
Supplier: { table: "supplier", labelColumn: "name" },
Item: { table: "item", labelColumn: "readableIdWithRevision" },
WorkCenter: { table: "workCenter", labelColumn: "name" },
Process: { table: "process", labelColumn: "name" },
Project: { table: "project", labelColumn: "name" }
};
/**
* Resolve the READABLE labels for a set of dimension values, keyed
* `<dimensionId>:<valueId>`. The dimension's entityType picks the source
* table (see DIMENSION_LABEL_SOURCES); Custom dimensions resolve through
* `dimensionValue`. Values whose entity row no longer exists are simply
* absent from the result (the caller degrades: unmapped → warn/drop).
* Throws on DB failure — callers are syncers whose push fails loudly.
*/
export async function resolveDimensionValueLabels(
db: Db,
args: { values: ReadonlyArray<JournalLineDimensionRef> }
): Promise<Map<string, string>> {
const labels = new Map<string, string>();
if (args.values.length === 0) return labels;
const dimensionIds = [...new Set(args.values.map((v) => v.dimensionId))];
const dimensions = await db
.selectFrom("dimension")
.select(["id", "entityType"])
.where("id", "in", dimensionIds)
.execute();
const entityTypeByDimensionId = new Map(
dimensions.map((dimension) => [dimension.id, String(dimension.entityType)])
);
// Group value ids per entityType (one query per source table)
const valueIdsByEntityType = new Map<string, Set<string>>();
for (const value of args.values) {
const entityType = entityTypeByDimensionId.get(value.dimensionId);
if (!entityType) continue;
let ids = valueIdsByEntityType.get(entityType);
if (!ids) {
ids = new Set<string>();
valueIdsByEntityType.set(entityType, ids);
}
ids.add(value.valueId);
}
const labelByValueId = new Map<string, string>();
for (const [entityType, ids] of valueIdsByEntityType) {
const source = DIMENSION_LABEL_SOURCES[entityType];
if (!source) continue;
const rows = await (db as Kysely<KyselyDatabase>)
.selectFrom(source.table as never)
.select([`${source.table}.id` as never, source.labelColumn as never])
.where(`${source.table}.id` as never, "in" as never, [...ids] as never)
.execute();
for (const row of rows as Array<Record<string, unknown>>) {
const id = row.id;
const label = row[source.labelColumn];
if (typeof id === "string" && typeof label === "string" && label) {
labelByValueId.set(id, label);
}
}
}
for (const value of args.values) {
const label = labelByValueId.get(value.valueId);
if (label !== undefined) {
labels.set(
buildDimensionValueMappingEntityId(value.dimensionId, value.valueId),
label
);
}
}
return labels;
}
/**
* The dimensions stamped on a set of journal lines, keyed by
* journalLine.id — the fetchLocal join every provider journal syncer
* runs (spec: `fetchLocal` joins `journalLineDimension`).
*/
export async function loadJournalLineDimensions(
db: Db,
args: { companyId: string; journalLineIds: ReadonlyArray<string> }
): Promise<Map<string, JournalLineDimensionRef[]>> {
const byLine = new Map<string, JournalLineDimensionRef[]>();
if (args.journalLineIds.length === 0) return byLine;
const rows = await db
.selectFrom("journalLineDimension")
.select(["journalLineId", "dimensionId", "valueId"])
.where("companyId", "=", args.companyId)
.where("journalLineId", "in", [...args.journalLineIds])
.orderBy("dimensionId", "asc")
.execute();
for (const row of rows) {
const existing = byLine.get(row.journalLineId);
const ref = { dimensionId: row.dimensionId, valueId: row.valueId };
if (existing) {
existing.push(ref);
} else {
byLine.set(row.journalLineId, [ref]);
}
}
return byLine;
}
/**
* Distinct dimension values present on POSTED journal lines for the
* slot-configured dimensions, minus already-mapped values, with resolved
* labels — the settings UI's unmapped-first value-mapping table source.
*/
export async function getUnmappedSlottedDimensionValues(
db: Db,
args: {
companyId: string;
integration: string;
slots: ReadonlyArray<Pick<PostingSyncDimensionSlot, "dimensionId">>;
}
): Promise<{ data: DimensionValueWithLabel[] | null; error: string | null }> {
try {
const slottedDimensionIds = [
...new Set(args.slots.map((slot) => slot.dimensionId))
];
if (slottedDimensionIds.length === 0) {
return { data: [], error: null };
}
const rows = await db
.selectFrom("journalLineDimension as jld")
.innerJoin("journalLine as jl", "jl.id", "jld.journalLineId")
.innerJoin("journal as j", "j.id", "jl.journalId")
.select(["jld.dimensionId", "jld.valueId"])
.distinct()
.where("jld.companyId", "=", args.companyId)
.where("j.companyId", "=", args.companyId)
.where("j.status", "=", "Posted")
.where("jld.dimensionId", "in", slottedDimensionIds)
.execute();
const mappings = await getDimensionValueMappings(db, {
companyId: args.companyId,
integration: args.integration
});
if (mappings.error) {
return { data: null, error: mappings.error };
}
const mapped = buildDimensionValueMappingLookup(mappings.data ?? []);
const unmapped: JournalLineDimensionRef[] = rows
.map((row) => ({ dimensionId: row.dimensionId, valueId: row.valueId }))
.filter(
(value) =>
!mapped.get(
buildDimensionValueMappingEntityId(value.dimensionId, value.valueId)
)
);
const labels = await resolveDimensionValueLabels(db, { values: unmapped });
const data = unmapped
.map((value) => ({
...value,
label:
labels.get(
buildDimensionValueMappingEntityId(value.dimensionId, value.valueId)
) ?? null
}))
.sort(
(a, b) =>
a.dimensionId.localeCompare(b.dimensionId) ||
(a.label ?? "").localeCompare(b.label ?? "")
);
return { data, error: null };
} catch (err) {
return { data: null, error: toErrorMessage(err) };
}
}
// /********************************************************\
// * Slot-config validation *
// \********************************************************/
/**
* Validate a dimension-slot configuration against the provider's declared
* targets. Errors (empty = valid): a dimension slotted more than once, a
* target the provider does not declare, a target used beyond its capacity
* (default 1), and more slots than the provider's structural cap.
*/
export function validateDimensionSlots(args: {
slots: ReadonlyArray<
Pick<PostingSyncDimensionSlot, "dimensionId" | "target">
>;
targets: ReadonlyArray<DimensionTarget>;
/** ProviderCapabilities.maxJournalDimensionSlots (or a provider constant). */
maxSlots?: number;
}): string[] {
const errors: string[] = [];
if (args.maxSlots !== undefined && args.slots.length > args.maxSlots) {
errors.push(
`Too many dimension slots: ${args.slots.length} configured, the provider supports at most ${args.maxSlots}.`
);
}
const targetsById = new Map(
args.targets.map((target) => [target.id, target])
);
const slotCountByDimension = new Map<string, number>();
const slotCountByTarget = new Map<string, number>();
for (const slot of args.slots) {
slotCountByDimension.set(
slot.dimensionId,
(slotCountByDimension.get(slot.dimensionId) ?? 0) + 1
);
slotCountByTarget.set(
slot.target,
(slotCountByTarget.get(slot.target) ?? 0) + 1
);
if (!targetsById.has(slot.target)) {
errors.push(
`Unknown provider target "${slot.target}" — the provider does not offer it.`
);
}
}
for (const [dimensionId, count] of slotCountByDimension) {
if (count > 1) {
errors.push(
`Dimension ${dimensionId} is slotted ${count} times; each dimension may map to at most one provider target.`
);
}
}
for (const [targetId, count] of slotCountByTarget) {
const target = targetsById.get(targetId);
if (!target) continue;
const capacity = target.capacity ?? 1;
if (count > capacity) {
errors.push(
`Provider target "${targetId}" is used by ${count} slots; it supports at most ${capacity}.`
);
}
}
return errors;
}
/**
* Effective autoCreate for a slot: the stored flag when present, else the
* provider default (Rillet: true — Field-value upsert is the expected
* flow; QBO/Xero: false — opt-in avoids surprise writes).
*/
export function resolveDimensionSlotAutoCreate(
slot: Pick<PostingSyncDimensionSlot, "autoCreate">,
providerDefault: boolean
): boolean {
return slot.autoCreate ?? providerDefault;
}
// /********************************************************\
// * autoCreate orchestration (per push) *
// \********************************************************/
/**
* Ensure every slotted dimension value on the journal's lines has a
* provider option id, creating missing provider options BY NAME for
* autoCreate slots. Provider-agnostic: the caller injects the provider
* write (`createExternalValue`) and the mapping persist; `mappings` is
* updated IN PLACE so the subsequent pre-flight and mapper see the new
* ids. Values whose label cannot be resolved (source entity deleted) are
* left unmapped — the warn/drop policy handles them downstream.
*/
export async function ensureDimensionValueExternalIds(args: {
lines: ReadonlyArray<{
dimensions?: JournalLineDimensionRef[] | null;
}>;
slots: ReadonlyArray<PostingSyncDimensionSlot>;
/** Provider default for slots without an explicit autoCreate flag. */
defaultAutoCreate: boolean;
/** `<dimensionId>:<valueId>` → provider option id; mutated in place. */
mappings: Map<string, string>;
resolveLabels: (
values: ReadonlyArray<JournalLineDimensionRef>
) => Promise<Map<string, string>>;
/** Create the provider option by NAME; returns its provider id. */
createExternalValue: (
slot: PostingSyncDimensionSlot,
label: string
) => Promise<string>;
persistMapping: (
value: JournalLineDimensionRef,
externalId: string,
label: string
) => Promise<void>;
}): Promise<{
created: Array<
JournalLineDimensionRef & { externalId: string; label: string }
>;
}> {
const created: Array<
JournalLineDimensionRef & { externalId: string; label: string }
> = [];
const autoCreateSlotsByDimension = new Map<
string,
PostingSyncDimensionSlot
>();
for (const slot of args.slots) {
if (resolveDimensionSlotAutoCreate(slot, args.defaultAutoCreate)) {
autoCreateSlotsByDimension.set(slot.dimensionId, slot);
}
}
if (autoCreateSlotsByDimension.size === 0) return { created };
// Distinct unmapped values on autoCreate slots
const pending = new Map<string, JournalLineDimensionRef>();
for (const line of args.lines) {
for (const dimension of line.dimensions ?? []) {
if (!autoCreateSlotsByDimension.has(dimension.dimensionId)) continue;
const key = buildDimensionValueMappingEntityId(
dimension.dimensionId,
dimension.valueId
);
if (args.mappings.get(key)) continue;
if (!pending.has(key)) {
pending.set(key, {
dimensionId: dimension.dimensionId,
valueId: dimension.valueId
});
}
}
}
if (pending.size === 0) return { created };
const labels = await args.resolveLabels([...pending.values()]);
for (const [key, value] of pending) {
const label = labels.get(key);
if (!label) continue; // unresolvable → warn/drop downstream
const slot = autoCreateSlotsByDimension.get(value.dimensionId);
if (!slot) continue;
const externalId = await args.createExternalValue(slot, label);
await args.persistMapping(value, externalId, label);
args.mappings.set(key, externalId);
created.push({ ...value, externalId, label });
}
return { created };
}