@campfire-interactive/master-data-client 4.13.0 → 4.14.0

package/dist/types.d.ts

@@ -97,12 +97,16 @@ export interface ListProgramsOptions {
     customerCompanyId?: string;
     /** @deprecated Use customerCompanyId. Removed in the next major. */
     oemCompanyId?: string;
+    /** Batch-get a specific set of programs by id — returns them regardless of
+     *  status. Comma-joined server-side; cap ~100/call for URL length and chunk
+     *  larger sets. The server bumps the page size to cover the ids. */
+    ids?: string[];
     include?: ('customerCompany' | 'oemCompany')[];
 }
 export interface GetProgramOptions {
     include?: ('customerCompany' | 'oemCompany')[];
 }
-export type QuoteStatus = 'draft' | 'costing_requested' | 'costing_in_progress' | 'costing_complete' | 'pricing' | 'routed_for_approval' | 'in_review' | 'approved' | 'submitted' | 'negotiating' | 'awarded' | 'lost';
+export type QuoteStatus = 'draft' | 'costing_requested' | 'costing_in_progress' | 'costing_complete' | 'pricing' | 'routed_for_approval' | 'in_review' | 'approved' | 'submitted' | 'negotiating' | 'awarded' | 'lost' | 'not_taken';
 /**
  * Who is driving the transition. Required on every status update so the
  * server can enforce role-gated transitions. `admin` is the escape hatch
@@ -133,6 +137,23 @@ export interface Quote {
     name: string | null;
     customerCompanyId: string;
     programId: string | null;
+    /**
+     * The OEM request this quote is one competing answer to — see {@link QuoteAsk}.
+     * Null means it competes with nothing and is awardable on its own, which is a
+     * legitimate state, not missing data.
+     */
+    askId: string | null;
+    /**
+     * @deprecated A DERIVED MIRROR of the quote's lines — read `quoteLines.list()`
+     * instead.
+     *
+     * Free text holding a part NUMBER (never a uuid), historically the quote's only
+     * part reference. A quote is multi-part now, and this reflects the FIRST line
+     * only, so it is lossy the moment a quote has more than one. Writes still work
+     * for the whole deprecation window (they transparently maintain the quote's
+     * single line), but new code should not read it as "the quote's part". Dropped
+     * in a later major. See the nextgen ADR `2026-08-05-multi-part-quotes.md`.
+     */
     partId: string | null;
     /**
      * The historical/parent quote this one was copied from. OMSF sets this when
@@ -211,6 +232,24 @@ export interface Quote {
      * column stays the canonical yearly curve.
      */
     effectiveVolumesByYear: EffectiveVolumeByYear[] | null;
+    /**
+     * The VEHICLE stream (added 2026-08-06) — how many vehicles the program
+     * builds, NOT how many parts we sell.
+     *
+     * This is what each {@link QuoteLine} bridges from: `vehicleAnnualVolume ×
+     * takeRate × partsPerVehicle` is that finished good's part volume. One quote
+     * covering four finished goods has ONE vehicle stream and four different part
+     * volumes, which is why the part columns above cannot serve as the input.
+     *
+     * **Null on every quote written before 2026-08-06**, and that is not a gap:
+     * those quotes' lines bridge from the part columns instead, at a 100/1 bridge
+     * that leaves the figure untouched. Read it as "does this quote calculate its
+     * line volumes, or carry them directly?" rather than as missing data.
+     */
+    vehicleAnnualVolume: number | null;
+    /** Per-year vehicle curve, same shape as {@link effectiveVolumesByYear}.
+     *  Bridged year by year onto each line. */
+    vehicleVolumesByYear: EffectiveVolumeByYear[] | null;
     /**
      * Customer-committed PART volume on ARBITRARY periods — the general form of
      * {@link effectiveVolumesByYear}, for deals tracked at a granularity the year
@@ -302,6 +341,230 @@ export interface SetEffectivePriceInput {
     /** Which app is writing — gated to 'omsf' | 'cpq' | 'admin' server-side. */
     callerRole: 'omsf' | 'cpq' | 'admin';
 }
+export type QuoteAskStatus = 'open' | 'resolved' | 'cancelled';
+export interface QuoteAsk {
+    id: string;
+    tenantId: string;
+    /** `ASK-YYYY-NNN`, minted server-side from an atomic per-(tenant, year) counter. */
+    askNumber: string;
+    name: string | null;
+    customerCompanyId: string;
+    /** Reporting only — NEVER used to decide competition. An opportunity spans
+     *  rounds; an ask is one round. */
+    opportunityId: string | null;
+    dueDate: string | null;
+    status: QuoteAskStatus;
+    /** Which quote won. A recorded fact — closing the siblings is a later phase. */
+    resolvedByQuoteId: string | null;
+    resolvedAt: string | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface QuoteAskSummary extends QuoteAsk {
+    /** How many quotes compete in this ask. Deliberately not a value aggregate. */
+    quoteCount: number;
+}
+/**
+ * A RANGE across the ask's quotes — deliberately not a total.
+ *
+ * The quotes are ALTERNATIVES: three of four lose on every multi-scenario RFQ by
+ * construction, so adding them multiply-counts the same business.
+ */
+export interface QuoteAskRange {
+    quoteCount: number;
+    minValue: number | null;
+    maxValue: number | null;
+    minBlendedMarginPct: number | null;
+    maxBlendedMarginPct: number | null;
+}
+export interface QuoteAskCompetingQuote {
+    id: string;
+    quoteNumber: string;
+    name: string | null;
+    status: QuoteStatus;
+    lines: QuoteLine[];
+    rollUp: QuoteLineRollUp;
+}
+export interface QuoteAskDetail extends QuoteAsk {
+    quotes: QuoteAskCompetingQuote[];
+    range: QuoteAskRange;
+}
+export interface CreateQuoteAskInput {
+    customerCompanyId: string;
+    name?: string | null;
+    opportunityId?: string | null;
+    dueDate?: string | null;
+}
+export interface UpdateQuoteAskInput {
+    name?: string | null;
+    dueDate?: string | null;
+    opportunityId?: string | null;
+    status?: QuoteAskStatus;
+    /** Required when resolving; must be one of this ask's own quotes. */
+    resolvedByQuoteId?: string | null;
+}
+export interface ListQuoteAsksOptions {
+    status?: QuoteAskStatus;
+    customerCompanyId?: string;
+    opportunityId?: string;
+}
+/** A per-year volume point. Same shape the quote header uses. */
+export interface QuoteLineVolumeByYear {
+    year: number;
+    effectiveVolume: number;
+}
+export interface QuoteLine {
+    id: string;
+    tenantId: string;
+    quoteId: string;
+    /** Document order. Also picks the line that supplies the deprecated `Quote.partId`. */
+    sortOrder: number;
+    /**
+     * The canonical master-data {@link Part}. NULL is legal — soft enforcement, so a
+     * part number not yet reconciled into the catalog can still be quoted. Denotes
+     * the BASE part per the part-identity ADR.
+     */
+    partId: string | null;
+    /** Required, denormalised. Carries the line on its own when `partId` is null. */
+    partNumber: string;
+    /** Engineering revision this line is quoted AT, when known. Never identity. */
+    revision: string | null;
+    /**
+     * Vehicle→part bridge, unique per line. At the defaults (100 / 1) the
+     * header→line volume projection is the IDENTITY.
+     */
+    takeRate: number | null;
+    partsPerVehicle: number | null;
+    /** Authored. Null inherits the header through the bridge. */
+    annualVolume: number | null;
+    /** Authored per-year series. Authoritative over `annualVolume` when present. */
+    effectiveVolumesByYear: QuoteLineVolumeByYear[] | null;
+    /** Authored offered price for this line. */
+    unitPrice: string | null;
+    /** Free text against an unhealthy line. Writable during review. */
+    note: string | null;
+    /** DERIVED — published only via `quoteLines.setEffectiveCost`. */
+    effectiveUnitCost: string | null;
+    effectiveCostSource: string | null;
+    effectiveCostBasis: string | null;
+    effectiveCostedAt: string | null;
+    effectiveCostedBy: string | null;
+    effectiveCostBreakdown: unknown | null;
+    /** DERIVED — published only via `quoteLines.setEffectivePrice`. */
+    effectiveUnitPrice: string | null;
+    effectivePriceSource: string | null;
+    effectivePriceBasis: string | null;
+    effectivePricedAt: string | null;
+    effectivePricedBy: string | null;
+    effectivePriceBreakdown: unknown | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Present when the line resolves to a catalog part. */
+    part?: {
+        id: string;
+        partNumber: string;
+        name: string;
+        partTypeId: string | null;
+    } | null;
+    /** Resolved figures — see {@link ResolvedQuoteLineTerms}. */
+    terms: ResolvedQuoteLineTerms;
+}
+/**
+ * A line's resolved terms. The `*Source` / `*FromLine` flags let a caller tell an
+ * authored figure from an inherited one without re-deriving the precedence.
+ */
+export interface ResolvedQuoteLineTerms {
+    annualVolume: number;
+    volumesByYear: QuoteLineVolumeByYear[] | null;
+    unitCost: number | null;
+    unitPrice: number | null;
+    value: number;
+    marginPct: number | null;
+    /**
+     * Which tier the volume came from: the line's own series, the line's own annual
+     * figure, or the quote header bridged through take rate × parts per vehicle.
+     */
+    volumeSource: 'line_years' | 'line_annual' | 'header_bridged';
+    costFromLine: boolean;
+    priceFromLine: boolean;
+}
+/**
+ * Consolidated figures for ONE quote's lines, computed on read.
+ *
+ * `blendedMarginPct` is value-weighted over the lines whose margin is KNOWN, not
+ * over the whole quote value — a blend diluted by parts with no cost yet is a
+ * worse number that is equally false. `linesWithoutMargin` reports that gap.
+ */
+export interface QuoteLineRollUp {
+    lineCount: number;
+    totalAnnualVolume: number;
+    totalValue: number;
+    blendedMarginPct: number | null;
+    linesWithoutMargin: number;
+    /** Lines whose part number isn't reconciled into the catalog yet. */
+    linesWithoutCatalogPart: number;
+}
+export interface QuoteLinesResponse {
+    quoteId: string;
+    quoteNumber: string;
+    lines: QuoteLine[];
+    rollUp: QuoteLineRollUp;
+}
+export interface QuoteLinesWithApprovalFlag extends QuoteLinesResponse {
+    /**
+     * True when the published figure landed on a quote already in approval — the
+     * approver signed off on a different number. Surfaced rather than silently
+     * absorbed; the caller decides whether to void and re-route.
+     */
+    invalidatesApproval: boolean;
+}
+export interface AddQuoteLineInput {
+    partNumber: string;
+    /** Omit to resolve from `partNumber`; pass `null` to pin it null. */
+    partId?: string | null;
+    revision?: string | null;
+    /** Defaults to the end of the list, so a new line can't take over the mirror. */
+    sortOrder?: number;
+    /** Percentage, 0–100. Defaults to 100. */
+    takeRate?: number;
+    /** Defaults to 1. */
+    partsPerVehicle?: number;
+    annualVolume?: number | null;
+    effectiveVolumesByYear?: QuoteLineVolumeByYear[] | null;
+    unitPrice?: number | null;
+    note?: string | null;
+}
+export interface UpdateQuoteLineInput {
+    partNumber?: string;
+    /** Omitted with a changed `partNumber` re-resolves the catalog link. */
+    partId?: string | null;
+    revision?: string | null;
+    sortOrder?: number;
+    takeRate?: number;
+    partsPerVehicle?: number;
+    annualVolume?: number | null;
+    effectiveVolumesByYear?: QuoteLineVolumeByYear[] | null;
+    unitPrice?: number | null;
+    note?: string | null;
+}
+export interface SetQuoteLineEffectiveCostInput {
+    unitCost: number;
+    /** Required — what the figure was costed against. */
+    costBasis: string;
+    /** Declared by the adapter. Defaults to 'cpq'. */
+    source?: string;
+    breakdown?: unknown;
+}
+export interface SetQuoteLineEffectivePriceInput {
+    unitPrice: number;
+    priceBasis: string;
+    source?: string;
+    breakdown?: unknown;
+}
 export interface CreateQuoteInput {
     /**
      * MIGRATION ESCAPE HATCH — do not set this from production code.
@@ -319,6 +582,10 @@ export interface CreateQuoteInput {
     name?: string;
     customerCompanyId: string;
     programId?: string;
+    /** Join the quote to an OEM request ({@link QuoteAsk}). Optional — a quote with
+     *  no ask competes with nothing and is awardable on its own. Validated to exist
+     *  in-tenant AND to belong to the same customer as the quote. */
+    askId?: string | null;
     partId?: string;
     /** Historical/parent quote this one was copied from. Validated to exist
      *  in-tenant on write; no DB FK. */
@@ -338,6 +605,12 @@ export interface CreateQuoteInput {
     eopPrecision?: SopEopPrecision;
     effectiveAnnualVolume?: number;
     effectiveVolumesByYear?: EffectiveVolumeByYear[];
+    /** The VEHICLE stream every line bridges from — vehicles the program builds,
+     *  not parts sold. Each line turns it into its own part volume with its take
+     *  rate and parts-per-vehicle. Omit it and the lines fall back to the part
+     *  columns, which is what pre-2026-08-06 quotes do. (4.12.0) */
+    vehicleAnnualVolume?: number;
+    vehicleVolumesByYear?: EffectiveVolumeByYear[];
     /** Arbitrary-period committed volume. Non-empty makes the two fields above
      *  derived — passing either alongside it is a 422. (4.8.0) */
     effectiveVolumesByPeriod?: EffectiveVolumeByPeriod[];
@@ -368,6 +641,9 @@ export interface UpdateQuoteInput {
     quoteNumber?: string;
     name?: string | null;
     programId?: string | null;
+    /** Join the quote to an OEM request ({@link QuoteAsk}), or `null` to detach it
+     *  (it then competes with nothing). Validated to match the quote's customer. */
+    askId?: string | null;
     partId?: string | null;
     /** Set to a quote id to record provenance, or `null` to clear it. */
     referenceQuoteId?: string | null;
@@ -385,6 +661,11 @@ export interface UpdateQuoteInput {
     eopPrecision?: SopEopPrecision | null;
     effectiveAnnualVolume?: number | null;
     effectiveVolumesByYear?: EffectiveVolumeByYear[] | null;
+    /** The VEHICLE stream. Editing it moves EVERY line's calculated volume at
+     *  once — one program build rate, many finished goods. `null` hands the lines
+     *  back to the part columns. (4.12.0) */
+    vehicleAnnualVolume?: number | null;
+    vehicleVolumesByYear?: EffectiveVolumeByYear[] | null;
     /** Full replace. Non-empty makes the yearly fields derived (writing them is a
      *  422); `null` or `[]` clears the schedule and hands them back. The last
      *  derived values are left in place — clearing stops maintaining them, it
@@ -724,6 +1005,7 @@ export interface MergePlantsRequest {
     survivorId: string;
     mergedIds: string[];
 }
+export type RateBookStatus = 'draft' | 'active' | 'archived';
 export type RateSourcingMode = 'fixed' | 'indexed';
 export type RateRollForwardMode = 'carry_forward_flagged' | 'blank_force_entry';
 export type RateValueOrigin = 'entered' | 'escalated' | 'overridden' | 'carried_forward';
@@ -1026,6 +1308,213 @@ export interface RateLookupResult {
         container: string | null;
     };
 }
+/**
+ * Bulk rate set for consumer per-run caching (e.g. CPQ costing). One read
+ * returns every book, every element + its values, the three catalogs, and the
+ * active legacy rate tables — enough to resolve rates in-memory for a whole
+ * calc run instead of N×M live `rates.lookup` calls. Decimals are strings.
+ */
+export interface RateSnapshot {
+    asOf: string;
+    books: Array<{
+        id: string;
+        name: string;
+        year: number;
+        status: string;
+        effectiveDate: string | null;
+        currency: string;
+        horizonStart: number;
+        horizonEnd: number;
+        escalationPct: string | null;
+        rollForwardMode: string;
+        publishedAt: string | null;
+    }>;
+    elements: Array<{
+        id: string;
+        scope: string;
+        plantId: string | null;
+        rateLineId: string | null;
+        gradeCode: string | null;
+        equipmentCode: string | null;
+        equipmentId: string | null;
+        skillClass: string | null;
+        lane: string | null;
+        mode: string | null;
+        container: string | null;
+        identityKey: string;
+        escalationPct: string | null;
+        values: Array<{
+            id: string;
+            bookId: string;
+            effectiveFrom: string | null;
+            effectiveTo: string | null;
+            origin: string;
+            rate: string | null;
+            ratePerKg: string | null;
+            uom: string;
+            currency: string;
+            sourcingMode: string;
+        }>;
+    }>;
+    rateLines: Array<{
+        id: string;
+        code: string;
+        label: string;
+        binding: string;
+        allowedUoms: string[];
+        defaultUom: string | null;
+        escalationDefault: string | null;
+        active: boolean;
+    }>;
+    rateGrades: Array<{
+        id: string;
+        code: string;
+        label: string;
+        allowedUoms: string[];
+        defaultUom: string;
+        density: string | null;
+        densityUnit: string | null;
+        active: boolean;
+    }>;
+    uoms: Array<{
+        id: string;
+        tenantId: string | null;
+        code: string;
+        label: string;
+        bindings: string[];
+        basis: string;
+        perBaseFactor: string | null;
+        needsDensity: boolean;
+        active: boolean;
+    }>;
+    legacyRateTables: Array<{
+        id: string;
+        name: string;
+        status: string;
+        year: number;
+        currency: string;
+        effectiveDate: string | null;
+        effectiveTo: string | null;
+        version: number;
+        entries: Array<{
+            id: string;
+            category: string;
+            subcategory: string;
+            region: string | null;
+            rate: number;
+            unit: string;
+            effectiveDate: string | null;
+            key: string | null;
+            type: string | null;
+            plantId: string | null;
+            plantSubtype: string | null;
+            skillTier: string | null;
+            lane: string | null;
+            mode: string | null;
+            sourcingMode: string | null;
+            currency: string | null;
+            density: number | null;
+            densityUnit: string | null;
+            ratePerKg: number | null;
+        }>;
+    }>;
+}
+export type RateCategoryKind = 'material' | 'packaging' | 'freight' | 'labor';
+/** The active book summary (`GET /v1/rate-books/active` → `{ book }`). */
+export interface RateBookSummary {
+    id: string;
+    name: string;
+    year: number;
+    status: RateBookStatus;
+    currency: string;
+    horizonStart: number;
+    horizonEnd: number;
+    rollForwardMode: RateRollForwardMode;
+    escalationPct: number;
+}
+/** A plant carrying rate elements in a book (`GET /v1/rate-books/:id/plants`). */
+export interface RateBookPlant {
+    plantId: string;
+    code: string | null;
+    name: string | null;
+    /** Plant-local currency; 'USD' when the opaque plantId has no local Plant row. */
+    currency: string;
+    elementCount: number;
+}
+/** A machine in a plant, collapsed to its base-year per-line summary. */
+export interface RateBookEquipment {
+    equipmentCode: string;
+    name: string | null;
+    processFamily: string | null;
+    /** Base-year value per rate line — the collapsed row's summary. */
+    summary: Array<{
+        lineCode: string;
+        rate: number;
+        uom: string;
+    }>;
+}
+/** Cursor-paginated equipment page (`GET .../plants/:plantId/equipment`). */
+export interface RateBookEquipmentPage {
+    items: RateBookEquipment[];
+    nextCursor: string | null;
+    total: number;
+}
+/** The rate-line × year matrix for one machine (`.../equipment/:code/rates`). */
+export interface MachineRateLine {
+    elementId: string;
+    rateLineId: string | null;
+    rateLineCode: string | null;
+    rateLineLabel: string | null;
+    /** Effective escalation pct (element override → rate-line default → book). */
+    escalationPct: number;
+    /** True when escalationPct is a row-level override (element.escalationPct set). */
+    escalationOverride: boolean;
+    /** Always true from master-data — no soft-deactivation is exposed. */
+    active: boolean;
+    values: Array<{
+        year: number;
+        rate: number;
+        uom: string;
+        currency: string;
+        origin: string;
+    }>;
+}
+/** A category (material/packaging/freight/labor) rate row, global merged with
+ *  a plant's overrides (`GET /v1/rate-books/:id/rates?kind=&plantId=`). */
+export interface CategoryRateRow {
+    elementId: string;
+    scope: 'plant' | 'global';
+    /** The global element this row overrides, when a plant row shadows a global. */
+    globalElementId: string | null;
+    label: string;
+    dimKey: string;
+    uom: string | null;
+    currency: string | null;
+    escalationPct: number;
+    escalationOverride: boolean;
+    /** Always true from master-data — no soft-deactivation is exposed. */
+    active: boolean;
+    values: Array<{
+        year: number;
+        rate: number;
+        origin: string;
+    }>;
+}
+/** A packaging-container option (`GET /v1/rate-containers` → `{ rows }`). */
+export interface RateContainer {
+    code: string;
+    label: string;
+}
+/** Options for the paginated equipment read. */
+export interface ListRateBookEquipmentOptions {
+    q?: string;
+    family?: string;
+    cursor?: string;
+    limit?: number;
+    /** 'rated' (default) = machines with a rate in the book; 'all' = union with
+     *  the plant's live machine master (for the add-entry picker). */
+    lens?: 'rated' | 'all';
+}
 export interface Equipment {
     id: string;
     tenantId: string;
@@ -1635,8 +2124,8 @@ export interface ListPartTypesOptions {
     /** When true, request only active types (drops archived). */
     activeOnly?: boolean;
 }
-export type AttributeDataType = 'text' | 'number' | 'boolean' | 'enum' | 'date';
-export type AttributeStatus = 'active' | 'archived';
+export type AttributeDataType = 'text' | 'number' | 'boolean' | 'enum' | 'date' | 'multi_select' | 'hierarchy';
+export type AttributeStatus = 'active' | 'deprecated' | 'archived';
 /** Typed rules stored per definition and enforced by the server on every
  *  attribute write. `min`/`max` are value bounds for `number` and length bounds
  *  for `text`; `regex` applies to `text`; `precision` is max decimal places for
@@ -1693,6 +2182,135 @@ export interface ListPartAttributesOptions {
     /** When true, request only active definitions (drops archived). */
     activeOnly?: boolean;
 }
+/** Per-type config + rules stored per definition (superset of AttributeValidation). */
+export interface AttributeValidationRules {
+    required?: boolean;
+    min?: number;
+    max?: number;
+    regex?: string;
+    precision?: number;
+    /** hierarchy: ordered level names, e.g. ["OEM","Platform","Program"]. */
+    levels?: string[];
+    minSelections?: number;
+    maxSelections?: number;
+    [k: string]: unknown;
+}
+export interface AttributeDefinition {
+    id: string;
+    tenantId: string;
+    entityType: string;
+    key: string;
+    label: string;
+    dataType: AttributeDataType;
+    unit: string | null;
+    /** Legacy inline enum values; prefer `attributeOptions` rows. */
+    options: string[] | null;
+    group: string | null;
+    groupId: string | null;
+    validation: AttributeValidationRules | null;
+    filterable: boolean;
+    analyticsVisible: boolean;
+    status: AttributeStatus;
+    sortOrder: number;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Present when the definition is fetched with its options (select/hierarchy). */
+    attributeOptions?: AttributeOption[];
+}
+export interface CreateAttributeDefinitionInput {
+    entityType: string;
+    key: string;
+    label: string;
+    dataType: AttributeDataType;
+    unit?: string | null;
+    options?: string[] | null;
+    groupId?: string | null;
+    validation?: AttributeValidationRules | null;
+    filterable?: boolean;
+    analyticsVisible?: boolean;
+    sortOrder?: number;
+}
+export interface UpdateAttributeDefinitionInput {
+    label?: string;
+    dataType?: AttributeDataType;
+    unit?: string | null;
+    options?: string[] | null;
+    groupId?: string | null;
+    validation?: AttributeValidationRules | null;
+    filterable?: boolean;
+    analyticsVisible?: boolean;
+    sortOrder?: number;
+    status?: AttributeStatus;
+}
+export interface ListAttributeDefinitionsOptions {
+    /** Required — the entity whose definitions to list ('opportunity', 'quote', …). */
+    entityType: string;
+    activeOnly?: boolean;
+    groupId?: string;
+}
+export interface AttributeGroup {
+    id: string;
+    tenantId: string;
+    entityType: string;
+    name: string;
+    sortOrder: number;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateAttributeGroupInput {
+    entityType: string;
+    name: string;
+    sortOrder?: number;
+}
+export interface UpdateAttributeGroupInput {
+    name?: string;
+    sortOrder?: number;
+}
+/** Disposition for a group's definitions when the group is deleted. */
+export interface DeleteAttributeGroupOptions {
+    reassignTo?: string;
+    archive?: boolean;
+}
+export interface AttributeOption {
+    id: string;
+    tenantId: string;
+    definitionId: string;
+    value: string;
+    label: string;
+    sortOrder: number;
+    parentId: string | null;
+    level: number;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateAttributeOptionInput {
+    value: string;
+    label?: string;
+    sortOrder?: number;
+    parentId?: string | null;
+}
+export interface UpdateAttributeOptionInput {
+    value?: string;
+    label?: string;
+    sortOrder?: number;
+}
+/** Result of the option Excel import (validate-preview or commit). */
+export interface ImportOptionsResult {
+    summary: {
+        rows: number;
+        roots: number;
+        total: number;
+        byLevel: Record<number, number>;
+        errors: string[];
+    };
+    committed: boolean;
+}
 export interface AuditLogEntry {
     id: string;
     tenantId: string | null;
@@ -1786,7 +2404,7 @@ export type SourceApp = 'master-data' | 'erfq' | 'cpq' | 'bom' | 'forecast' | 'o
  *  "Empty" means SQL NULL only — a stored '', 0, false, or 0.0 counts as
  *  populated and will not be overwritten by fill_empty. */
 export type MergePolicy = 'overwrite' | 'fill_empty';
-export type ImportTargetField = 'name' | 'legalName' | 'code' | 'taxId' | 'dunsNumber' | 'website' | 'logoUrl' | 'roles' | 'email' | 'phone' | 'role' | 'type' | 'description' | 'street' | 'city' | 'stateProvince' | 'postalCode' | 'country' | 'category' | 'parent_company_ref' | 'companyCode' | 'locationCode' | 'region' | 'headcount' | 'annualCapacityHours' | 'currentUtilization' | 'riskLevel' | 'numShifts' | 'hoursPerShift' | 'workingDaysPerYear' | 'indirectHeadcountPct' | 'currency' | 'effectiveDate' | 'effectiveTo' | 'libraryCode' | 'kind' | 'plantCode' | 'skillTier' | 'materialCode' | 'regionCode' | 'lane' | 'rate' | 'unit' | 'sourcingMode' | 'indexRef' | 'notes' | 'partNumber' | 'manufacturingPartNumber' | 'customerPartNumber' | 'partType' | 'manufacturer' | 'partCategoryCode' | 'quality' | 'revision' | 'uom' | 'weightPerUnit' | 'recycledPct' | 'pcfPerUnit' | 'releaseStatus' | 'leadTime' | 'customerCompanyCode' | 'customerCompanyName' | 'sopDate' | 'eopDate' | 'displayOrder' | 'label' | 'sortOrder' | 'processFamily' | 'capacityHoursPerYear' | 'cavities' | 'availabilityPct' | 'performancePct' | 'defaultHeadcount' | 'defaultAutomationPct' | 'defaultMachinesPerOperator' | 'defaultSetupCrew' | 'perUsd' | 'effectiveFrom' | 'quoteNumber' | 'programCode' | 'partId' | 'regionName' | 'annualVolume' | 'apw' | 'mpw' | 'targetPrice' | 'dueDate' | 'key' | 'dataType' | 'options' | 'group' | 'required' | 'min' | 'max' | 'regex' | 'precision' | 'basis' | 'bindings' | 'perBaseFactor' | 'needsDensity' | 'binding' | 'allowedUoms' | 'defaultUom' | 'escalationDefault' | 'density' | 'densityUnit';
+export type ImportTargetField = 'name' | 'legalName' | 'code' | 'taxId' | 'dunsNumber' | 'website' | 'logoUrl' | 'roles' | 'email' | 'phone' | 'role' | 'type' | 'description' | 'street' | 'city' | 'stateProvince' | 'postalCode' | 'country' | 'category' | 'parent_company_ref' | 'companyCode' | 'companyName' | 'locationCode' | 'region' | 'headcount' | 'annualCapacityHours' | 'currentUtilization' | 'riskLevel' | 'numShifts' | 'hoursPerShift' | 'workingDaysPerYear' | 'indirectHeadcountPct' | 'currency' | 'effectiveDate' | 'effectiveTo' | 'libraryCode' | 'kind' | 'plantCode' | 'skillTier' | 'materialCode' | 'regionCode' | 'lane' | 'rate' | 'unit' | 'sourcingMode' | 'indexRef' | 'notes' | 'partNumber' | 'manufacturingPartNumber' | 'customerPartNumber' | 'partType' | 'manufacturer' | 'partCategoryCode' | 'quality' | 'revision' | 'uom' | 'weightPerUnit' | 'recycledPct' | 'pcfPerUnit' | 'releaseStatus' | 'leadTime' | 'customerCompanyCode' | 'customerCompanyName' | 'sopDate' | 'eopDate' | 'displayOrder' | 'label' | 'sortOrder' | 'processFamily' | 'capacityHoursPerYear' | 'cavities' | 'availabilityPct' | 'performancePct' | 'defaultHeadcount' | 'defaultAutomationPct' | 'defaultMachinesPerOperator' | 'defaultSetupCrew' | 'perUsd' | 'effectiveFrom' | 'quoteNumber' | 'programCode' | 'partId' | 'regionName' | 'annualVolume' | 'apw' | 'mpw' | 'targetPrice' | 'dueDate' | 'status' | 'key' | 'dataType' | 'options' | 'group' | 'required' | 'min' | 'max' | 'regex' | 'precision' | 'basis' | 'bindings' | 'perBaseFactor' | 'needsDensity' | 'binding' | 'allowedUoms' | 'defaultUom' | 'escalationDefault' | 'density' | 'densityUnit';
 export interface ImportSession {
     id: string;
     tenantId: string;
@@ -2062,10 +2680,20 @@ export interface BulkArchiveResult {
         errors: number;
     };
 }
+/** Ownership verdict carried on an *enforced* entity's read/list response
+ *  `meta` (Master Data Ownership Phase 4). Present only for enforced elements
+ *  (Plant today). `readOnly` ⇒ the element is externally owned and Campfire
+ *  edits are rejected server-side; the UI renders read-only + `editHint`. */
+export interface OwnershipMeta {
+    readOnly: boolean;
+    ownerSystem: string;
+    editHint: string | null;
+}
 export interface ApiMeta {
     requestId: string;
     timestamp: string;
     resolvedFrom?: string;
+    ownership?: OwnershipMeta;
 }
 export interface ListMeta extends ApiMeta {
     nextCursor: string | null;
@@ -2079,6 +2707,29 @@ export interface DuplicateWarning {
     matchName: string;
     score: number;
 }
+export type OwnerType = 'campfire' | 'external';
+/** One catalog element merged with its (optional) stored ownership row. The
+ *  GET response fills catalog defaults where a tenant has no row. */
+export interface MasterDataElementOwnership {
+    element: string;
+    label: string;
+    category: string;
+    ownerType: OwnerType;
+    /** Owning system display name; 'Campfire' when Campfire-owned. */
+    systemName: string;
+    syncMethod: string | null;
+    /** Opaque integrations Source id (external only) — traceability, not a FK. */
+    sourceRef: string | null;
+    updatedAt: string | null;
+    updatedBy: string | null;
+}
+export interface SetOwnershipInput {
+    ownerType: OwnerType;
+    /** Required when ownerType is 'external'. */
+    systemName?: string;
+    syncMethod?: string;
+    sourceRef?: string;
+}
 export interface SingleResponse<T> {
     data: T;
     meta: ApiMeta;
@@ -2100,6 +2751,10 @@ export interface ListCompaniesOptions {
     status?: 'active' | 'archived' | 'all';
     quality?: 'draft' | 'verified';
     role?: 'supplier' | 'customer' | 'oem';
+    /** Batch-get a specific set of companies by id — returns them regardless of
+     *  status. Comma-joined server-side; cap ~100/call for URL length and chunk
+     *  larger sets. The server bumps the page size to cover the ids. */
+    ids?: string[];
     include?: ('contacts' | 'locations')[];
 }
 export interface GetCompanyOptions {