Skip to content

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.

97.8 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import { defineServiceFn } from "@carbon/api/service-fn.server";
import { paged, payload, unwrap } from "@carbon/api/service-tools.server";
import { CONTROLLED_ENVIRONMENT } from "@carbon/auth";
import { bustApiKeyCache, hashApiKey } from "@carbon/auth/auth.server";
import {
  blockSchema,
  type DocumentBlock,
  type DocumentSettings,
  type DocumentTheme,
  documentSectionPlacementSchema,
  documentSettingsSchema,
  documentTemplateTypeSchema,
  sectionConfigSchema,
  themeSchema
} from "@carbon/documents/template";
import { integrations as availableIntegrations } from "@carbon/ee";
import {
  getUnmappedRequiredAccounts,
  JOURNAL_ENTRY_SOURCE_TYPES,
  POSTING_POLICY,
  suggestAccountMatchesWithAI,
  upsertAccountMappings,
  upsertDimensionValueMapping,
  validateDimensionSlots
} from "@carbon/ee/accounting";
import { deleteApiKey, upsertApiKey } from "@carbon/ee/api-keys.server";
import {
  disableAuditLog,
  enableAuditLog,
  getArchiveDownloadUrl
} from "@carbon/ee/audit.server";
import { updateConsoleSetting } from "@carbon/ee/console.server";
import { EntitlementError } from "@carbon/ee/entitlements.server";
import { getIntegrationServerHooks } from "@carbon/ee/hooks.server";
import {
  disconnectConnection,
  readConnection,
  renameConnection
} from "@carbon/ee/integrations/connections";
import type { OeeDevice } from "@carbon/ee/oee";
import {
  deleteWorkCenterDevice,
  upsertWorkCenterDevice
} from "@carbon/ee/oee.server";
import { ONSHAPE_V2_INTEGRATION_ID } from "@carbon/ee/onshape";
import { isIntegrationWhitelisted } from "@carbon/ee/plan";
import { companyHasFeature } from "@carbon/ee/plan.server";
import { updateRequireMfaSetting } from "@carbon/ee/two-factor.server";
import { trigger } from "@carbon/jobs";
import { getLogger } from "@carbon/logger";
import {
  createPrintJob,
  deletePrinterRoute,
  getPrintingSettings,
  getPrintJob,
  getPrintJobContent,
  type PrintingSettings,
  printerRouteValidator,
  reprintValidator,
  setContextAssignment,
  updateAssignmentValidator,
  updatePrintingSettings,
  upsertPrinterRoute
} from "@carbon/printing";
import { invalidatePrinterCache } from "@carbon/printing/printing.server";
import type { JSONContent } from "@carbon/react";
import { getStripeConnectAccountId } from "@carbon/stripe/send-sales-invoice.server";
import { getBillingPortalRedirectUrl } from "@carbon/stripe/stripe.server";
import { datetime, unchecked } from "@carbon/utils";
import { parseTime } from "@internationalized/date";
import { nanoid } from "nanoid";
import { z } from "zod";
import { plmReleaseControl } from "~/modules/items/items.models";
import { notifyScheduleInputsChanged } from "~/modules/production/production.service";
import {
  invalidateCompanyTimeZone,
  invokePosting,
  isActiveCompanyEmployee
} from "~/modules/shared/shared.service";
import { sendMfaRequiredEmails } from "~/services/mfa-email.server";
import * as accountingPostings from "../accounting/accounting.service";
import { fromServerFn } from "../shared/shared.service";
import {
  accountMappingEntrySchema,
  apiKeyValidator,
  calculatedShelfLifeInputScopes,
  companyValidator,
  dimensionSlotEntrySchema,
  dimensionValueMappingEntrySchema,
  expiredEntityPolicies,
  incompletePickingListPolicies,
  invoiceAutomations,
  kanbanLabelSizes,
  kanbanOutputTypes,
  purchasePriceUpdateTimingTypes,
  returnPickedMaterialTimings,
  serialNumberTimings,
  subsidiaryValidator
} from "./settings.models";
import * as service from "./settings.service";

const logger = getLogger("erp", "settings");
// ─── Operations (`defineServiceFn`) ─────────────────────────────────────────
// What the routes, the API and MCP all run. A settings page has ONE update
// operation: it takes the page's fields, all optional, and writes the ones
// sent. An absent field keeps its stored value, so one form never blanks a
// neighbouring setting.
const notificationGroup = z.array(z.string().min(1));

const billingAddressInput = z.object({
  name: z.string().nullable().optional(),
  addressLine1: z.string().nullable().optional(),
  addressLine2: z.string().nullable().optional(),
  city: z.string().nullable().optional(),
  state: z.string().nullable().optional(),
  postalCode: z.string().nullable().optional(),
  countryCode: z.string().nullable().optional(),
  phone: z.string().nullable().optional(),
  fax: z.string().nullable().optional(),
  email: z.string().email().nullable().optional()
});
/**
 * Update the accounting settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: whether money shows its
 * trailing zeros, the fixed-asset tax depreciation (on or off, its rate, and
 * the deferred tax liability and expense accounts on the company's account
 * defaults), and the ASC 842 lease policy (the classification thresholds,
 * the default lessor discount rate and lessee incremental borrowing rate in
 * percentage points, the short-term lease expedient, and how many days ahead
 * a lease's owner is reminded). The lease policy applies to later lease
 * activations only.
 *
 * @mcp
 */
export const updateAccountingSettings = defineServiceFn({
  input: z.object({
    showCurrencyTrailingZeros: z.boolean().optional(),
    assetTaxDepreciationEnabled: z.boolean().optional(),
    assetTaxRate: z.number().min(0).max(100).nullable().optional(),
    deferredTaxLiabilityAccountId: z.string().min(1).optional(),
    deferredTaxExpenseAccountId: z.string().min(1).optional(),
    leaseMajorPartThresholdPercent: z.number().gt(0).max(100).optional(),
    leaseSubstantiallyAllThresholdPercent: z.number().gt(0).max(100).optional(),
    leaseDefaultDiscountRate: z.number().min(0).optional(),
    leaseIncrementalBorrowingRate: z.number().min(0).optional(),
    leaseShortTermExpedient: z.boolean().optional(),
    leaseReminderDays: z.number().int().min(0).optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const {
      deferredTaxLiabilityAccountId,
      deferredTaxExpenseAccountId,
      ...settings
    } = input;

    const saved = await service.saveCompanySettings(
      ctx,
      settings,
      "Failed to update accounting settings"
    );
    if (saved) return saved;

    const accounts = service.sentFields({
      deferredTaxLiabilityAccountId,
      deferredTaxExpenseAccountId
    });
    if (Object.keys(accounts).length > 0) {
      const { error } = await ctx.asCaller.supabase
        .from("accountDefault")
        .update({ ...accounts, updatedBy: ctx.auditUserId })
        .eq("companyId", ctx.company.id);
      if (error) {
        return ctx.error(
          "internal",
          "Failed to update the deferred tax accounts",
          error
        );
      }
    }
    return input;
  }
});

/**
 * Write the journals the accounting cutover would have written for documents posted without one.
 *
 * @remarks
 * A company that enabled accounting before the enable wrote journals has
 * documents posted on or after its cutover with no journal. This runs the
 * `journal-legacy-documents` posting, which journals each of them, and
 * returns how many documents it journaled. Not published: it needs two
 * modules' permissions, which the API gate cannot state yet.
 */
export const writeMissingJournals = defineServiceFn({
  input: z.object({}),
  permission: { update: ["settings", "accounting"] },
  async run(ctx) {
    const result = await invokePosting(
      ctx,
      "journal-legacy-documents",
      {},
      accountingPostings.repairLegacyJournals
    );
    if (result.error) {
      return fromServerFn(
        ctx,
        result.error,
        "Failed to write the missing journals"
      );
    }
    const { movementCostRows: _, ...families } = result.data.legacyJournals;
    return {
      documents: Object.values(families).reduce((sum, count) => sum + count, 0)
    };
  }
});

/**
 * Update the inventory settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: what a kanban card prints
 * (label, QR code or URL) and the size its label prints at (a letter sheet of
 * six, or a 4" x 2" or 3" x 2" thermal label), the shelf-life and expiry policy (the near-expiry
 * warning in days, null to turn the badges off; the default shelf life of a
 * new item; which inputs a calculated expiry reads; and what consuming an
 * expired entity does), whether finishing a picking list with unpicked
 * material warns or refuses, and when unconsumed picked material is returned
 * (when the job completes, or when each operation is done), and whether a
 * new receipt's lines start at a received quantity of 0 instead of the
 * quantity still to receive.
 *
 * @mcp
 */
export const updateInventorySettings = defineServiceFn({
  input: z.object({
    kanbanOutput: z.enum(kanbanOutputTypes).optional(),
    kanbanLabelSize: z.enum(kanbanLabelSizes).optional(),
    inventoryShelfLife: z
      .object({
        nearExpiryWarningDays: z.number().int().min(0).max(365).nullable(),
        defaultShelfLifeDays: z.number().int().min(1).max(3650),
        calculatedInputScope: z.enum(calculatedShelfLifeInputScopes),
        expiredEntityPolicy: z.enum(expiredEntityPolicies)
      })
      .optional(),
    incompletePickingListPolicy: z
      .enum(incompletePickingListPolicies)
      .optional(),
    returnPickedMaterialTiming: z.enum(returnPickedMaterialTimings).optional(),
    receiptQuantitiesStartAtZero: z.boolean().optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const saved = await service.saveCompanySettings(
      ctx,
      input,
      "Failed to update inventory settings"
    );
    return saved ?? input;
  }
});

/**
 * Update the invoicing settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: what happens to a recurring
 * invoice when the daily job creates it, the receivables email (the Reply-To
 * and a CC on automated invoice emails), who is also notified about
 * invoices, whether documents print the centralized receivables billing
 * address, that address itself (a null field clears it), and the default CC
 * on customer emails. "Post and Send via Stripe" is refused until Stripe is
 * connected in Integrations, or every recurring invoice would be held.
 *
 * @mcp
 */
export const updateInvoicingSettings = defineServiceFn({
  input: z.object({
    invoiceAutomation: z.enum(invoiceAutomations).optional(),
    accountsReceivableEmail: z.string().email().nullable().optional(),
    invoiceNotificationGroup: notificationGroup.optional(),
    accountsReceivableAddress: z.boolean().optional(),
    accountsReceivableBillingAddress: billingAddressInput.optional(),
    defaultCustomerCc: z.array(z.string().email()).optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const { accountsReceivableBillingAddress, ...settings } = input;

    if (
      settings.invoiceAutomation === "Post and Send via Stripe" &&
      !(await getStripeConnectAccountId(ctx.asSystem.supabase, ctx.company.id))
    ) {
      return ctx.error("rule", "Connect Stripe in Integrations first");
    }

    const saved = await service.saveCompanySettings(
      ctx,
      settings,
      "Failed to update invoicing settings"
    );
    if (saved) return saved;

    if (accountsReceivableBillingAddress) {
      const { error } = await ctx.asCaller.supabase
        .from("companyAccountsReceivableBillingAddress")
        .upsert({
          id: ctx.company.id,
          ...service.sentFields(accountsReceivableBillingAddress),
          updatedBy: ctx.auditUserId
        });
      if (error) {
        return ctx.error(
          "internal",
          "Failed to update the accounts receivable billing address",
          error
        );
      }
    }
    return input;
  }
});

/**
 * Update the items settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: whether material ids are
 * generated from their properties, whether material sizes use metric units,
 * whether item ids may contain lowercase letters, whether the BoM explorer
 * shows readable ids, how strictly a released revision controls changes
 * (off, warn or enforce), whether a backflush consumes only from a line's Pull
 * From storage unit (strict backflush), and whether a strict backflush refuses
 * to take that storage unit below zero.
 *
 * @mcp
 */
export const updateItemsSettings = defineServiceFn({
  input: z.object({
    materialGeneratedIds: z.boolean().optional(),
    useMetric: z.boolean().optional(),
    allowLowercaseItemIds: z.boolean().optional(),
    showBomExplorerReadableId: z.boolean().optional(),
    requireBackflushStorageUnit: z.boolean().optional(),
    preventNegativeBackflush: z.boolean().optional(),
    plmReleaseControl: z.enum(plmReleaseControl).optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const saved = await service.saveCompanySettings(
      ctx,
      input,
      "Failed to update items settings"
    );
    return saved ?? input;
  }
});

/**
 * Update the production settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: who is notified when an
 * inventory or a sales job completes, whether opening an operation starts its
 * timer, whether the job traveler lists materials and operations, whether
 * tracked material is pre-selected without a picking list, when a produced
 * unit draws its serial number (when the job is created, when it is released,
 * or the first time the unit is worked on, scrapped or received), and whether
 * one location requires an assigned operator before the scheduler places work
 * there. The staffing rule lives on the location row and is written for the
 * company's own location only, so a settings admin without the resources
 * permission can still set it. Changing it re-plans the location.
 *
 * @mcp
 */
export const updateProductionSettings = defineServiceFn({
  input: z.object({
    inventoryJobCompletedNotificationGroup: notificationGroup.optional(),
    salesJobCompletedNotificationGroup: notificationGroup.optional(),
    autoStartOperationTimer: z.boolean().optional(),
    includeMaterialsOnTraveler: z.boolean().optional(),
    includeOperationsOnTraveler: z.boolean().optional(),
    autoSelectMaterialWithoutPickingList: z.boolean().optional(),
    serialNumberTiming: z.enum(serialNumberTimings).optional(),
    locationStaffing: z
      .object({
        locationId: z.string().min(1),
        requiresStaffing: z.boolean()
      })
      .optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const { locationStaffing, ...settings } = input;

    const saved = await service.saveCompanySettings(
      ctx,
      settings,
      "Failed to update production settings"
    );
    if (saved) return saved;

    if (locationStaffing) {
      const { locationId, requiresStaffing } = locationStaffing;
      const current = await ctx.asSystem.supabase
        .from("location")
        .select("requiresStaffing")
        .eq("id", locationId)
        .eq("companyId", ctx.company.id)
        .maybeSingle();
      if (current.error) {
        return ctx.error(
          "internal",
          "Failed to update the staffing requirement",
          current.error
        );
      }
      if (current.data === null) {
        return ctx.error("notFound", "Location not found");
      }
      if (current.data.requiresStaffing !== requiresStaffing) {
        const { error } = await ctx.asSystem.supabase
          .from("location")
          .update({ requiresStaffing })
          .eq("id", locationId)
          .eq("companyId", ctx.company.id);
        if (error) {
          return ctx.error(
            "internal",
            "Failed to update the staffing requirement",
            error
          );
        }
        // The scheduler places work only where an operator is manned while
        // this is on, so the location's plan changes either way.
        await notifyScheduleInputsChanged(
          ctx.company.id,
          "location",
          requiresStaffing
            ? "Staffing requirement enabled"
            : "Staffing requirement disabled",
          locationId
        );
      }
    }
    return input;
  }
});

/**
 * Update the purchasing settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: whether documents print the
 * centralized payables billing address, that address itself (a null field
 * clears it), whether a supplier needs a contact with an email before its
 * documents issue, whether approving a purchase order needs the approver's
 * signature on file, when a purchase updates the item's price (on invoice post
 * or on order finalize), whether a receipt updates the supplier lead time,
 * whether supplier readable ids show, who is notified about supplier quotes,
 * and the default CC on supplier emails.
 *
 * @mcp
 */
export const updatePurchasingSettings = defineServiceFn({
  input: z.object({
    accountsPayableAddress: z.boolean().optional(),
    accountsPayableBillingAddress: billingAddressInput.optional(),
    requireSupplierContactAndLocation: z.boolean().optional(),
    requirePurchaseOrderApprovalSignature: z.boolean().optional(),
    purchasePriceUpdateTiming: z
      .enum(purchasePriceUpdateTimingTypes)
      .optional(),
    updateLeadTimesOnReceipt: z.boolean().optional(),
    showSupplierReadableId: z.boolean().optional(),
    supplierQuoteNotificationGroup: notificationGroup.optional(),
    defaultSupplierCc: z.array(z.string().email()).optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const { accountsPayableBillingAddress, ...settings } = input;

    const saved = await service.saveCompanySettings(
      ctx,
      settings,
      "Failed to update purchasing settings"
    );
    if (saved) return saved;

    if (accountsPayableBillingAddress) {
      const { error } = await ctx.asCaller.supabase
        .from("companyAccountsPayableBillingAddress")
        .update({
          ...service.sentFields(accountsPayableBillingAddress),
          updatedBy: ctx.auditUserId
        })
        .eq("id", ctx.company.id);
      if (error) {
        return ctx.error(
          "internal",
          "Failed to update the accounts payable billing address",
          error
        );
      }
    }
    return input;
  }
});

/**
 * Update the quality settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: whether an inspection needs a
 * second person to sign it off, the sampling standard inspection plans use,
 * the open-issue target on the quality dashboard, and who is notified when a
 * gauge goes out of calibration.
 *
 * @mcp
 */
export const updateQualitySettings = defineServiceFn({
  input: z.object({
    enforceInspectionFourEyes: z.boolean().optional(),
    samplingStandard: z.enum(["ANSI_Z1_4", "ISO_2859_1"]).optional(),
    qualityIssueTarget: z.number().int().min(0).optional(),
    gaugeCalibrationExpiredNotificationGroup: notificationGroup.optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const saved = await service.saveCompanySettings(
      ctx,
      input,
      "Failed to update quality settings"
    );
    return saved ?? input;
  }
});

/**
 * Update the resources settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: who is notified about a new
 * suggestion, and who is notified about a maintenance, quality, operations or
 * other dispatch.
 *
 * @mcp
 */
export const updateResourcesSettings = defineServiceFn({
  input: z.object({
    suggestionNotificationGroup: notificationGroup.optional(),
    maintenanceDispatchNotificationGroup: notificationGroup.optional(),
    qualityDispatchNotificationGroup: notificationGroup.optional(),
    operationsDispatchNotificationGroup: notificationGroup.optional(),
    otherDispatchNotificationGroup: notificationGroup.optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const { suggestionNotificationGroup, ...settings } = input;

    // The suggestion group lives on the company row, not its settings.
    if (suggestionNotificationGroup) {
      const { error } = await ctx.asCaller.supabase
        .from("company")
        .update({ suggestionNotificationGroup })
        .eq("id", ctx.company.id);
      if (error) {
        return ctx.error(
          "internal",
          "Failed to update suggestion notifications",
          error
        );
      }
    }

    const saved = await service.saveCompanySettings(
      ctx,
      settings,
      "Failed to update dispatch notifications"
    );
    return saved ?? input;
  }
});

/**
 * Update the sales settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: whether a customer needs a
 * contact and location, whether customer readable ids show, the digital quote
 * (on or off, who is notified, and whether accepting one asks for a purchase
 * order), who is notified when an RFQ is ready and when a sales rule is
 * broken, and the default markup per cost category on a quote line.
 *
 * @mcp
 */
export const updateSalesSettings = defineServiceFn({
  input: z.object({
    requireCustomerContactAndLocation: z.boolean().optional(),
    showCustomerReadableId: z.boolean().optional(),
    digitalQuoteEnabled: z.boolean().optional(),
    digitalQuoteNotificationGroup: notificationGroup.optional(),
    digitalQuoteIncludesPurchaseOrders: z.boolean().optional(),
    rfqReadyNotificationGroup: notificationGroup.optional(),
    salesRuleNotificationGroup: notificationGroup.optional(),
    quoteLineCategoryMarkups: z
      .object({
        materialCost: z.number().min(0),
        partCost: z.number().min(0),
        toolCost: z.number().min(0),
        consumableCost: z.number().min(0),
        laborCost: z.number().min(0),
        machineCost: z.number().min(0),
        overheadCost: z.number().min(0),
        outsideCost: z.number().min(0)
      })
      .optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const saved = await service.saveCompanySettings(
      ctx,
      input,
      "Failed to update sales settings"
    );
    return saved ?? input;
  }
});

/**
 * Update the people settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest: whether timecards are on, and
 * whether console (kiosk) mode is on. Console mode is a Business plan
 * feature. Turning it on creates the "Console Operator" employee type, and
 * for a signed-in user who has no console PIN yet it generates one: `pin` is
 * returned once and can never be read back. `pinError` says why that PIN
 * could not be created; console mode is on regardless. A key caller gets no
 * PIN.
 */
export const updatePeopleSettings = defineServiceFn({
  input: z.object({
    timeCardEnabled: z.boolean().optional(),
    consoleEnabled: z.boolean().optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const { consoleEnabled, ...settings } = input;

    const saved = await service.saveCompanySettings(
      ctx,
      settings,
      "Failed to update timecard settings"
    );
    if (saved) return saved;
    if (consoleEnabled === undefined) {
      return { ...input, pin: null, pinError: null };
    }

    let update: Awaited<ReturnType<typeof updateConsoleSetting>>;
    try {
      update = await updateConsoleSetting(
        ctx.asCaller.supabase,
        ctx.asSystem.pg,
        ctx.company.id,
        consoleEnabled,
        ctx.actor.type === "user" ? ctx.actor.userId : undefined
      );
    } catch (err) {
      if (!(err instanceof EntitlementError)) throw err;
      return ctx.error(
        "entitlement",
        "Console mode requires the Business plan"
      );
    }
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update console mode",
        update.error
      );
    }
    return { ...input, pin: update.pin, pinError: update.pinError };
  }
});

/**
 * Turn the company-wide two-factor requirement on or off.
 *
 * @remarks
 * Requiring two-factor authentication is a Business plan feature; turning it
 * off is always allowed, so a downgraded company is never locked out. When it
 * goes from off to on, every active employee is emailed. It is not announced
 * when the stored value was already on, when the stored value cannot be read,
 * or in a controlled environment, where two-factor is mandatory from the day
 * of deployment.
 *
 * @mcp
 */
export const updateSecuritySettings = defineServiceFn({
  input: z.object({ requireMfa: z.boolean() }),
  permission: { update: "settings" },
  async run(ctx, { requireMfa }) {
    // Read first: the switch re-submits on every flip, and a toggle that
    // lands on the value it already had must not re-announce.
    const previous = await ctx.asCaller.supabase
      .from("companySettings")
      .select("requireMfa")
      .eq("id", ctx.company.id)
      .single();

    let update: Awaited<ReturnType<typeof updateRequireMfaSetting>>;
    try {
      update = await updateRequireMfaSetting(
        ctx.asCaller.supabase,
        ctx.company.id,
        requireMfa
      );
    } catch (err) {
      if (!(err instanceof EntitlementError)) throw err;
      return ctx.error(
        "entitlement",
        "Upgrade to Business to require two-factor authentication"
      );
    }
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update two-factor requirement",
        update.error
      );
    }

    if (
      !CONTROLLED_ENVIRONMENT &&
      requireMfa &&
      previous.data?.requireMfa === false
    ) {
      await sendMfaRequiredEmails(ctx.asSystem.supabase, ctx.company.id);
    }
    return { requireMfa };
  }
});

const employeeOrNone = z.string().min(1).nullable();

/**
 * Update the planning settings.
 *
 * @remarks
 * Writes the fields sent and leaves the rest. The planning action owner
 * ladder: the company default responsible employee, one location's
 * responsible employee, and one item group's at a location (null clears a
 * rung, so it inherits from the one above). Each employee must be an active
 * employee of the company. A location is a resources record: without the
 * resources update permission it is refused. Then whether purchase orders
 * the planning pages raise skip approval, the reschedule tolerance in days,
 * the default planning horizon in days (null for no time fence), the forecast
 * consumption window in weekly periods back and forward, the time of day
 * scheduled MRP runs on the company's clock ("HH:MM" or "HH:MM:SS"; null runs
 * it every 3 hours), and whether the planning grids and demand forecasts head
 * their weeks by calendar week (ISO 8601 week of the year) rather than
 * counting from the present week.
 *
 * @mcp
 */
export const updatePlanningSettings = defineServiceFn({
  input: z.object({
    defaultResponsibleEmployee: employeeOrNone.optional(),
    locationResponsibleEmployee: z
      .object({
        locationId: z.string().min(1),
        responsibleEmployee: employeeOrNone
      })
      .optional(),
    itemGroupResponsibleEmployee: z
      .object({
        locationId: z.string().min(1),
        itemPostingGroupId: z.string().min(1),
        responsibleEmployee: employeeOrNone
      })
      .optional(),
    skipApprovalForPlanningPurchaseOrders: z.boolean().optional(),
    useCalendarWeeks: z.boolean().optional(),
    rescheduleToleranceDays: z.number().int().min(0).max(365).optional(),
    defaultPlanningHorizonDays: z
      .number()
      .int()
      .min(0)
      .max(3650)
      .nullable()
      .optional(),
    forecastConsumptionBackwardPeriods: z
      .number()
      .int()
      .min(0)
      .max(52)
      .optional(),
    forecastConsumptionForwardPeriods: z
      .number()
      .int()
      .min(0)
      .max(52)
      .optional(),
    mrpRunTime: z
      .string()
      .regex(/^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$/, {
        message: "Choose a time for the daily MRP run"
      })
      .nullable()
      .optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const refused = service.nothingSent(ctx, input);
    if (refused) return refused;
    const {
      locationResponsibleEmployee: location,
      itemGroupResponsibleEmployee: itemGroup,
      mrpRunTime,
      ...settings
    } = input;

    const employees = [
      settings.defaultResponsibleEmployee,
      location?.responsibleEmployee,
      itemGroup?.responsibleEmployee
    ].filter((id): id is string => !!id);
    for (const employeeId of new Set(employees)) {
      if (
        !(await isActiveCompanyEmployee(
          ctx.asCaller.supabase,
          ctx.company.id,
          employeeId
        ))
      ) {
        return ctx.error("rule", "Choose an employee of this company");
      }
    }

    const saved = await service.saveCompanySettings(
      ctx,
      {
        ...settings,
        mrpRunTime:
          mrpRunTime === undefined
            ? undefined
            : mrpRunTime && parseTime(mrpRunTime).toString()
      },
      "Failed to update planning settings"
    );
    if (saved) return saved;

    if (location) {
      const result = await service.setLocationResponsibleEmployee(
        ctx.asCaller.supabase,
        {
          companyId: ctx.company.id,
          locationId: location.locationId,
          employeeId: location.responsibleEmployee,
          userId: ctx.auditUserId
        }
      );
      if (result.error) {
        return ctx.error(
          "internal",
          "Failed to update location ownership",
          result.error
        );
      }
      // No row back: the location is not this company's, or the caller lacks
      // resources_update and row-level security matched nothing.
      if ((result.data?.length ?? 0) === 0) {
        return ctx.error(
          "forbidden",
          "You do not have permission to change this location"
        );
      }
    }

    if (itemGroup) {
      const result = await service.upsertItemPostingGroupResponsibility(
        ctx.asCaller.supabase,
        {
          companyId: ctx.company.id,
          locationId: itemGroup.locationId,
          itemPostingGroupId: itemGroup.itemPostingGroupId,
          employeeId: itemGroup.responsibleEmployee,
          userId: ctx.auditUserId
        }
      );
      if (result.error) {
        return ctx.error(
          "internal",
          "Failed to update item group ownership",
          result.error
        );
      }
    }
    return input;
  }
});
/**
 * Update the company's details.
 *
 * @remarks
 * Writes the company's name, address, time zone, base currency, tax and
 * registration numbers and contact details. Changing the base currency also
 * deletes every exchange-rate override, in the same transaction: an override
 * is denominated in the old base and would rate every new document wrong.
 * The company's cached time zone is dropped, so a new one applies at once.
 *
 * @mcp
 */
export const updateCompanyDetails = defineServiceFn({
  input: companyValidator,
  permission: { update: "settings" },
  async run(ctx, company) {
    const existing = await ctx.asCaller.supabase
      .from("company")
      .select("baseCurrencyCode")
      .eq("id", ctx.company.id)
      .single();

    const baseCurrencyChanged =
      !!existing.data?.baseCurrencyCode &&
      existing.data.baseCurrencyCode !== company.baseCurrencyCode;

    if (baseCurrencyChanged) {
      try {
        await service.updateCompanyWithBaseCurrencyChange(
          ctx.asSystem.pg,
          ctx.company.id,
          { ...company, updatedBy: ctx.auditUserId }
        );
      } catch (err) {
        return ctx.error("internal", "Failed to update company", err);
      }
    } else {
      const update = await service.updateCompany(
        ctx.asCaller.supabase,
        ctx.company.id,
        { ...company, updatedBy: ctx.auditUserId }
      );
      if (update.error) {
        return ctx.error("internal", "Failed to update company", update.error);
      }
    }

    await invalidateCompanyTimeZone(ctx.company.id);
    return { id: ctx.company.id };
  }
});
/**
 * Create a company in a new company group, for the caller.
 *
 * @remarks
 * Inserts the company, seeds it (chart of accounts, sequences, the caller's
 * employee record and permissions), creates its Headquarters location at the
 * company's address and the caller's job there. In a controlled environment
 * audit logging is on from the start. Returns the new company and its group,
 * so the caller can switch to it.
 */
export const createCompany = defineServiceFn({
  input: companyValidator,
  permission: { update: ["settings", "users"] },
  async run(ctx, company) {
    const client = ctx.asSystem.supabase;
    const inserted = await service.insertCompany(client, company);
    if (inserted.error || !inserted.data?.id) {
      return ctx.error("internal", "Failed to create company", inserted.error);
    }
    const companyId = inserted.data.id;

    const seed = await invokePosting(
      { db: ctx.asSystem.pg, companyId, userId: ctx.auditUserId },
      "seed-company",
      { identityOnly: false },
      service.seedCompany
    );
    if (seed.error) {
      return ctx.error("internal", "Failed to seed company", seed.error);
    }

    const { baseCurrencyCode: _, ...location } = company;
    const headquarters = await service.createHeadquarters(
      ctx,
      companyId,
      location
    );
    if (headquarters) return headquarters;

    const { data } = await client
      .from("company")
      .select("companyGroupId")
      .eq("id", companyId)
      .single();
    return { companyId, companyGroupId: data?.companyGroupId ?? "" };
  }
});

/**
 * Create a company in the caller's company group.
 *
 * @remarks
 * Open to Carbon staff, and to the companies the `multi-company-management`
 * flag turns it on for. A parent is required, and it must be a company of the
 * caller's own group: seeding joins the new company to its parent's group,
 * so a parent from another group would place it inside another tenant. Then
 * as for a new company: insert, seed, the Headquarters location and the
 * caller's job there.
 */
export const createSubsidiary = defineServiceFn({
  input: subsidiaryValidator,
  permission: { create: "settings" },
  async run(ctx, subsidiary) {
    const refused = await service.refuseUnlessCanManageCompanies(ctx);
    if (refused) return refused;

    const { id: _, parentCompanyId, ...company } = subsidiary;
    const client = ctx.asSystem.supabase;

    // Without a parent, seeding would start a new company group: that is
    // creating a company, not a subsidiary, and has its own permissions.
    if (!parentCompanyId) {
      return ctx.error("validation", "A subsidiary needs a parent company");
    }
    const parent = await client
      .from("company")
      .select("id")
      .eq("id", parentCompanyId)
      .eq("companyGroupId", ctx.company.groupId)
      .maybeSingle();
    if (parent.error || !parent.data) {
      return ctx.error("notFound", "Parent company not found", parent.error);
    }

    const inserted = await service.insertCompany(client, company);
    if (inserted.error || !inserted.data?.id) {
      return ctx.error("internal", "Failed to create company", inserted.error);
    }
    const companyId = inserted.data.id;

    const seed = await invokePosting(
      { db: ctx.asSystem.pg, companyId, userId: ctx.auditUserId },
      "seed-company",
      { parentCompanyId, identityOnly: false },
      service.seedCompany
    );
    if (seed.error) {
      return ctx.error("internal", "Failed to seed company", seed.error);
    }

    const { baseCurrencyCode: __, ...location } = company;
    const headquarters = await service.createHeadquarters(
      ctx,
      companyId,
      location
    );
    return headquarters ?? { companyId };
  }
});

/**
 * Update a company of the caller's company group.
 *
 * @remarks
 * Open to Carbon staff, and to the companies the `multi-company-management`
 * flag turns it on for. The company and its new parent must both be in the
 * caller's group. Writes the company's details and its parent, then drops its
 * cached time zone. A base-currency change also clears the company's
 * exchange-rate overrides in the same transaction, as `updateCompanyDetails`
 * does: they are denominated in the old base.
 */
export const updateSubsidiaryDetails = defineServiceFn({
  input: subsidiaryValidator.safeExtend({ id: z.string() }),
  permission: { update: "settings" },
  async run(ctx, { id, ...subsidiary }) {
    const refused = await service.refuseUnlessCanManageCompanies(ctx);
    if (refused) return refused;

    const client = ctx.asSystem.supabase;
    const current = await client
      .from("company")
      .select("baseCurrencyCode")
      .eq("id", id)
      .eq("companyGroupId", ctx.company.groupId)
      .maybeSingle();
    if (current.error || !current.data) {
      return ctx.error("notFound", "Company not found", current.error);
    }
    if (subsidiary.parentCompanyId) {
      const parent = await client
        .from("company")
        .select("id")
        .eq("id", subsidiary.parentCompanyId)
        .eq("companyGroupId", ctx.company.groupId)
        .maybeSingle();
      if (parent.error || !parent.data) {
        return ctx.error("notFound", "Parent company not found", parent.error);
      }
    }

    if (
      subsidiary.baseCurrencyCode &&
      subsidiary.baseCurrencyCode !== current.data.baseCurrencyCode
    ) {
      try {
        await service.updateCompanyWithBaseCurrencyChange(
          ctx.asSystem.pg,
          id,
          { ...subsidiary, updatedBy: ctx.auditUserId },
          Object.keys(subsidiaryValidator.shape).filter((key) => key !== "id")
        );
      } catch (error) {
        return ctx.error("internal", "Failed to update subsidiary", error);
      }
    } else {
      const result = await service.updateSubsidiary(ctx.asCaller.supabase, id, {
        ...subsidiary,
        updatedBy: ctx.auditUserId
      });
      if (result.error) {
        return ctx.error(
          "internal",
          "Failed to update subsidiary",
          result.error
        );
      }
    }
    await invalidateCompanyTimeZone(id);
    return { id };
  }
});
/**
 * Create or update a printer route.
 *
 * @remarks
 * A printer route is a printer the company prints to: its name, format (ZPL
 * labels or PDF documents), media size, URL and optional API key, location
 * and template. With an `id` the company's route is updated, without one a
 * route is created. The cached printer routing is dropped, so the change
 * applies to the next print. Not published: the server POSTs to the URL it
 * saves, so an API caller could aim it at any address.
 */
export const savePrinterRoute = defineServiceFn({
  input: printerRouteValidator,
  permission: { update: "settings" },
  async run(ctx, route) {
    const result = await upsertPrinterRoute(ctx.asCaller.supabase, {
      id: route.id || undefined,
      companyId: ctx.company.id,
      name: route.name,
      format: route.format,
      mediaSizeId: route.mediaSizeId || null,
      printerUrl: route.printerUrl,
      apiKey: route.apiKey || null,
      locationId: route.locationId || null,
      templateId: route.templateId || null
    });
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to save printer route",
        result.error
      );
    }
    await invalidatePrinterCache(ctx.company.id);
    return { created: !route.id };
  }
});

/**
 * Send a test label to a printer route.
 *
 * @remarks
 * Prints one ZPL test label, sized to the route's media, on the company's
 * printer route. Only a ZPL route with a media size can print one. The
 * printer must answer within 10 seconds.
 */
export const testPrinterRoute = defineServiceFn({
  input: z.object({ routeId: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { routeId }) {
    const { data: route } = await ctx.asCaller.supabase
      .from("printerRoute")
      .select("printerUrl, format, mediaSizeId, apiKey")
      .eq("id", routeId)
      .eq("companyId", ctx.company.id)
      .single();
    if (!route) return ctx.error("notFound", "Printer route not found");

    const testLabel = service.generateTestLabel(
      route.format,
      route.mediaSizeId
    );
    if (!testLabel) {
      return ctx.error(
        "rule",
        "Test print is only supported for ZPL label printers with a media size configured."
      );
    }

    const headers: Record<string, string> = {
      "Content-Type": "application/octet-stream"
    };
    if (route.apiKey) headers["X-API-Key"] = route.apiKey;

    try {
      const response = await fetch(route.printerUrl, {
        method: "POST",
        headers,
        body: testLabel,
        signal: AbortSignal.timeout(10_000)
      });
      if (!response.ok) {
        return ctx.error(
          "unavailable",
          `Print failed (${response.status} ${response.statusText})`
        );
      }
    } catch (err) {
      return ctx.error(
        "unavailable",
        `Print failed: ${err instanceof Error ? err.message : "Unknown error"}`,
        err
      );
    }
    return { routeId };
  }
});

/**
 * Delete a printer route.
 *
 * @remarks
 * Deletes the company's printer route, then clears it from every printer
 * assignment that named it (a location's default, its shipping and receiving
 * printers, and its work centers), so no assignment points at a printer that
 * is gone. The cached printer routing is dropped.
 *
 * @mcp destructive
 */
export const removePrinterRoute = defineServiceFn({
  input: z.object({ id: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { id }) {
    const client = ctx.asCaller.supabase;
    const result = await deletePrinterRoute(client, id, ctx.company.id);
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to delete printer route",
        result.error
      );
    }

    const { data: existing } = await getPrintingSettings(
      client,
      ctx.company.id
    );
    const current = existing?.printing as PrintingSettings | null;
    if (current?.assignments) {
      let dirty = false;
      const assignments = { ...current.assignments };
      for (const [locationId, location] of Object.entries(assignments)) {
        if (!location) continue;
        const next = { ...location };
        if (next.defaultPrinterRouteId === id) {
          next.defaultPrinterRouteId = null;
          dirty = true;
        }
        for (const context of [
          "shipping",
          "receiving",
          "inventory",
          "kanban"
        ] as const) {
          const assigned = next[context];
          if (assigned?.printerRouteId === id) {
            next[context] = { ...assigned, printerRouteId: null };
            dirty = true;
          }
        }
        if (next.workCenters) {
          const workCenters = { ...next.workCenters };
          for (const [workCenterId, workCenter] of Object.entries(
            workCenters
          )) {
            if (workCenter?.printerRouteId === id) {
              workCenters[workCenterId] = {
                ...workCenter,
                printerRouteId: null
              };
              dirty = true;
            }
          }
          next.workCenters = workCenters;
        }
        assignments[locationId] = next;
      }
      if (dirty) {
        await updatePrintingSettings(client, ctx.company.id, {
          ...current,
          assignments
        });
      }
    }

    await invalidatePrinterCache(ctx.company.id);
    return { id };
  }
});

/**
 * Assign a printer to a location, one of its contexts or a work center.
 *
 * @remarks
 * Sets which printer route a location prints to by default, for shipping,
 * for receiving, or at one of its work centers (`contextId` names the work
 * center), and whether it prints automatically. An empty route clears the
 * assignment, so the context falls back to the location's default. The
 * cached printer routing is dropped.
 *
 * @mcp
 */
export const assignPrinter = defineServiceFn({
  input: updateAssignmentValidator,
  permission: { update: "settings" },
  async run(ctx, assignment) {
    const client = ctx.asCaller.supabase;
    const { data: existing } = await getPrintingSettings(
      client,
      ctx.company.id
    );
    const current = (existing?.printing as PrintingSettings | null) ?? {
      assignments: {}
    };
    const updated = setContextAssignment(
      current,
      assignment.locationId,
      assignment.context,
      {
        printerRouteId: assignment.printerRouteId || null,
        autoPrint: assignment.autoPrint
      },
      assignment.contextId
    );

    const result = await updatePrintingSettings(
      client,
      ctx.company.id,
      updated
    );
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to update the printer assignment",
        result.error
      );
    }
    await invalidatePrinterCache(ctx.company.id);
    return { locationId: assignment.locationId };
  }
});

/**
 * Print a print job again.
 *
 * @remarks
 * Queues a new print job with the company's original job's content, to its
 * printer or to `printerUrl` when given, and starts its delivery. A job still
 * generating has no content and cannot be reprinted. Not published: the
 * server POSTs to `printerUrl`, so an API caller could aim it at any address.
 */
export const reprintPrintJob = defineServiceFn({
  input: reprintValidator,
  permission: { update: "settings" },
  async run(ctx, { printJobId, printerUrl }) {
    const client = ctx.asCaller.supabase;
    const [original, originalMeta] = await Promise.all([
      getPrintJobContent(client, printJobId, ctx.company.id),
      getPrintJob(client, printJobId, ctx.company.id)
    ]);
    if (
      original.error ||
      !original.data ||
      originalMeta.error ||
      !originalMeta.data
    ) {
      return ctx.error(
        "notFound",
        "Failed to load print job",
        original.error ?? originalMeta.error
      );
    }
    if (!original.data.content || !original.data.contentType) {
      return ctx.error("rule", "Cannot reprint a job that is still generating");
    }

    const job = await createPrintJob(client, {
      companyId: ctx.company.id,
      contentType: original.data.contentType as "zpl" | "pdf",
      content: original.data.content,
      printerUrl: printerUrl || originalMeta.data.printerUrl,
      sourceDocument: originalMeta.data.sourceDocument,
      sourceDocumentId: originalMeta.data.sourceDocumentId,
      sourceDocumentReadableId:
        originalMeta.data.sourceDocumentReadableId ?? undefined,
      description: originalMeta.data.description,
      status: "queued",
      origin: "reprint",
      createdBy: ctx.auditUserId
    });
    if (job.error || !job.data) {
      return ctx.error("internal", "Failed to create reprint", job.error);
    }

    try {
      await trigger("print-job-deliver", {
        printJobId: job.data.id,
        companyId: ctx.company.id
      });
    } catch (err) {
      logger.error("Failed to trigger delivery", {
        companyId: ctx.company.id,
        error: err
      });
    }
    return { printJobId: job.data.id };
  }
});

/**
 * Delete a print job.
 *
 * @remarks
 * Deletes the company's print job from the print queue history.
 *
 * @mcp destructive
 */
export const deletePrintJob = defineServiceFn({
  input: z.object({ printJobId: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { printJobId }) {
    const { error } = await ctx.asCaller.supabase
      .from("printJob")
      .delete()
      .eq("id", printJobId)
      .eq("companyId", ctx.company.id);
    if (error) return ctx.error("internal", "Failed to delete job", error);
    return { id: printJobId };
  }
});

/** What a print job printed: its ZPL or PDF content. */
export const viewPrintJobContent = defineServiceFn({
  input: z.object({ printJobId: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { printJobId }) {
    const content = await getPrintJobContent(
      ctx.asCaller.supabase,
      printJobId,
      ctx.company.id
    );
    if (content.error || !content.data) {
      return ctx.error("notFound", "Failed to load content", content.error);
    }
    return {
      printJobId: content.data.id,
      content: content.data.content,
      contentType: content.data.contentType
    };
  }
});

/**
 * Save a document's layout.
 *
 * @remarks
 * Writes the company's template for one document type: its blocks, theme,
 * settings and the header and footer sections it uses. The logo and header
 * layout (`headerConfig`) is edited with the template but lives on the
 * company-wide header section, so it is saved onto that section in the same
 * transaction as the template, with the section's name and content kept, and
 * applies wherever the header is used. A built-in header section is forked
 * into the company's own copy.
 *
 * @mcp
 */
export const saveDocumentTemplate = defineServiceFn({
  input: z.object({
    documentType: documentTemplateTypeSchema,
    blocks: z.array(blockSchema),
    theme: themeSchema,
    settings: documentSettingsSchema,
    headerSectionId: z.string().optional(),
    footerSectionId: z.string().optional(),
    headerConfig: sectionConfigSchema.optional()
  }),
  permission: { update: "settings" },
  async run(ctx, template) {
    const { headerConfig, headerSectionId } = template;

    let header: Parameters<typeof service.upsertDocumentTemplate>[2];
    if (headerConfig && headerSectionId) {
      const resolved = await service.resolveSections(
        ctx.asCaller.supabase,
        ctx.company.id,
        [headerSectionId]
      );
      const section = resolved[headerSectionId];
      header = {
        id: headerSectionId,
        name: section?.name ?? "Default Header",
        content: (section?.content ?? {
          type: "doc",
          content: []
        }) as JSONContent,
        config: headerConfig as Record<string, unknown>
      };
    }

    // The header layout and the template land together or not at all.
    try {
      await service.upsertDocumentTemplate(
        ctx.asSystem.pg,
        {
          companyId: ctx.company.id,
          documentType: template.documentType,
          blocks: template.blocks as DocumentBlock[],
          theme: template.theme as DocumentTheme,
          settings: template.settings as DocumentSettings,
          headerSectionId: headerSectionId || null,
          footerSectionId: template.footerSectionId || null,
          userId: ctx.auditUserId
        },
        header
      );
    } catch (err) {
      return ctx.error("internal", "Failed to save document layout", err);
    }
    return { documentType: template.documentType };
  }
});

/**
 * Create or update a shared document section.
 *
 * @remarks
 * A section is company-wide rich text placed in a document's header, body or
 * footer. With an `id` the section is updated; editing a built-in section
 * forks it into the company's own copy under the same id, which then
 * overrides the built-in everywhere it is used. Without an `id` a section is
 * created.
 *
 * @mcp
 */
export const saveDocumentSection = defineServiceFn({
  input: z.object({
    id: z.string().optional(),
    name: z.string().min(1),
    placement: documentSectionPlacementSchema,
    content: z.record(z.string(), z.unknown()),
    config: sectionConfigSchema.optional()
  }),
  permission: { update: "settings" },
  async run(ctx, { id, name, placement, content, config }) {
    const result = await service.upsertDocumentSection(ctx.asCaller.supabase, {
      id,
      companyId: ctx.company.id,
      name,
      placement,
      content: content as JSONContent,
      config: config as Record<string, unknown> | undefined,
      ...(id ? { updatedBy: ctx.auditUserId } : { createdBy: ctx.auditUserId })
    });
    if (result.error) {
      return ctx.error("internal", "Failed to save section", result.error);
    }
    return { saved: true };
  }
});

/**
 * Delete a shared document section.
 *
 * @remarks
 * Templates refer to their header and footer sections without a foreign
 * key: a template that used the deleted section renders without it.
 *
 * @mcp destructive
 */
export const removeDocumentSection = defineServiceFn({
  input: z.object({ id: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { id }) {
    const result = await service.deleteDocumentSection(
      ctx.asCaller.supabase,
      id,
      ctx.company.id
    );
    if (result.error) {
      return ctx.error("internal", "Failed to delete section", result.error);
    }
    return { id };
  }
});

const apiKeyFields = {
  name: apiKeyValidator.shape.name,
  expiresAt: apiKeyValidator.shape.expiresAt,
  /** Per module, the actions the key may run: `{ "sales": ["view"] }`. */
  scopes: z.record(z.string(), z.array(z.string()))
};
/**
 * Create an API key.
 *
 * @remarks
 * Generates the key, stores only its hash and last five characters, and
 * returns the raw key once: it can never be read back. API keys are a
 * Business plan feature.
 */
export const createApiKey = defineServiceFn({
  input: z.object(apiKeyFields),
  permission: { update: "users" },
  async run(ctx, { name, scopes, expiresAt }) {
    const rawKey = `crbn_${nanoid()}`;
    let created: Awaited<ReturnType<typeof upsertApiKey>>;
    try {
      created = await upsertApiKey(ctx.asCaller.supabase, {
        name,
        scopes,
        expiresAt: expiresAt || undefined,
        rawKey,
        keyHash: hashApiKey(rawKey),
        keyPreview: rawKey.slice(-5),
        companyId: ctx.company.id,
        createdBy: ctx.auditUserId
      });
    } catch (err) {
      return service.apiKeysEntitlement(ctx, err);
    }
    const key = created.data && "key" in created.data ? created.data.key : null;
    if (created.error || !key) {
      return ctx.error("internal", "Failed to create API key", created.error);
    }
    return { key };
  }
});

/**
 * Update an API key's name, scopes and expiry.
 *
 * @remarks
 * The key itself never changes. Its cached authentication is dropped, so a
 * narrower scope or an earlier expiry applies at once.
 */
export const updateApiKey = defineServiceFn({
  input: z.object({ id: z.string().min(1), ...apiKeyFields }),
  permission: { update: "users" },
  async run(ctx, { id, name, scopes, expiresAt }) {
    let updated: Awaited<ReturnType<typeof upsertApiKey>>;
    try {
      updated = await upsertApiKey(ctx.asCaller.supabase, {
        id,
        name,
        scopes,
        expiresAt: expiresAt || undefined
      });
    } catch (err) {
      return service.apiKeysEntitlement(ctx, err);
    }
    if (updated.error) {
      return ctx.error("internal", "Failed to update API key", updated.error);
    }
    // A scope or expiry edit must not keep authenticating from the 30s cache.
    await service.invalidateApiKeyCache(id, ctx.company.id);
    return { id };
  }
});

/**
 * Delete an API key.
 *
 * @remarks
 * The key stops authenticating: its cached authentication is dropped before
 * the delete (the key's hash cannot be read once the row is gone) and again
 * after it, in case a request re-cached the live row in between.
 */
export const revokeApiKey = defineServiceFn({
  input: z.object({ id: z.string().min(1) }),
  permission: { update: "users" },
  async run(ctx, { id }) {
    const keyHash = await service.invalidateApiKeyCache(id, ctx.company.id);
    let deleted: Awaited<ReturnType<typeof deleteApiKey>>;
    try {
      deleted = await deleteApiKey(ctx.asCaller.supabase, id);
    } catch (err) {
      return service.apiKeysEntitlement(ctx, err);
    }
    if (deleted.error) {
      return ctx.error("internal", "Failed to delete API key", deleted.error);
    }
    if (keyHash) await bustApiKeyCache(keyHash);
    return { id };
  }
});

/**
 * Disconnect an integration.
 *
 * @remarks
 * Marks the company's integration inactive, runs the integration's own
 * uninstall step (removing its webhooks, for example) and drops its cached
 * health. Integrations outside the always-available set need the plan's
 * integrations feature.
 *
 * @mcp destructive
 */
export const deactivateCompanyIntegration = defineServiceFn({
  input: z.object({ id: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { id }) {
    if (
      !isIntegrationWhitelisted(id) &&
      !(await companyHasFeature(ctx.asCaller.supabase, ctx.company.id, {
        feature: "INTEGRATIONS"
      }))
    ) {
      return ctx.error("entitlement", "Integrations require an upgraded plan");
    }

    const integration = availableIntegrations.find((i) => i.id === id);
    if (!integration) return ctx.error("notFound", "Integration not found");

    const update = await service.deactivateIntegration(ctx.asCaller.supabase, {
      id,
      companyId: ctx.company.id,
      updatedBy: ctx.auditUserId
    });
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to disconnect integration",
        update.error
      );
    }

    const hooks = getIntegrationServerHooks(id);
    if (hooks?.onUninstall) await hooks.onUninstall(ctx.company.id);

    await service.invalidateIntegrationHealthCache(id, ctx.company.id);
    return { id, name: integration.name };
  }
});

/**
 * Rename an account connected to a workflow integration.
 *
 * @remarks
 * The name a workflow step's account picker shows. Names are unique per app.
 */
export const renameIntegrationConnection = defineServiceFn({
  input: z.object({ id: z.string().min(1), name: z.string().trim().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { id, name }) {
    // The table is read-only to API roles, so every write goes through the
    // service role, scoped by the caller's company.
    const connection = await readConnection(
      ctx.asSystem.supabase,
      ctx.company.id,
      id
    );
    if (connection === null) {
      return ctx.error("notFound", "Connection not found");
    }

    const update = await renameConnection(
      ctx.asSystem.supabase,
      ctx.company.id,
      id,
      name,
      ctx.auditUserId
    );
    // Names are unique per app: the unique index refuses a taken one.
    if (update.error?.code === "23505") {
      return ctx.error(
        "conflict",
        "An account is already called that — pick a different name."
      );
    }
    if (update.error) {
      return ctx.error("internal", "Failed to rename connection", update.error);
    }
    return { id };
  }
});

/**
 * Disconnect an account connected to a workflow integration.
 *
 * @remarks
 * Drops the account's token and marks it Revoked. The account stays listed, so
 * a workflow step that uses it says "reconnect" rather than naming an account
 * that is gone.
 */
export const disconnectIntegrationConnection = defineServiceFn({
  input: z.object({ id: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { id }) {
    const connection = await readConnection(
      ctx.asSystem.supabase,
      ctx.company.id,
      id
    );
    if (connection === null) {
      return ctx.error("notFound", "Connection not found");
    }

    try {
      await disconnectConnection(
        ctx.asSystem.supabase,
        ctx.company.id,
        connection.pieceName,
        id,
        ctx.auditUserId
      );
    } catch (err) {
      return ctx.error("internal", "Failed to disconnect", err);
    }

    // The card's badge is cached (five minutes while healthy) and its health is
    // computed from these rows, so without this Settings keeps saying "Healthy"
    // for an account the builder already treats as disconnected.
    await service.invalidateIntegrationHealthCache(
      connection.pieceName,
      ctx.company.id
    );
    return { id };
  }
});

/**
 * Turn audit logging on.
 *
 * @remarks
 * Records every change to the company's audited tables from now on. Audit
 * logging is a Business plan feature.
 *
 * @mcp
 */
export const enableCompanyAuditLog = defineServiceFn({
  input: z.object({}),
  permission: { update: "settings" },
  async run(ctx) {
    try {
      await enableAuditLog(ctx.asCaller.supabase, ctx.company.id);
    } catch (err) {
      if (err instanceof EntitlementError) {
        return ctx.error(
          "entitlement",
          "Upgrade to Business to enable audit logging"
        );
      }
      return ctx.error("internal", "Failed to enable audit logging", err);
    }
    return { auditLogEnabled: true };
  }
});

/**
 * Turn audit logging off.
 *
 * @remarks
 * Stops recording changes; the log written so far is kept. A controlled
 * environment cannot turn audit logging off.
 *
 * @mcp destructive
 */
export const disableCompanyAuditLog = defineServiceFn({
  input: z.object({}),
  permission: { update: "settings" },
  async run(ctx) {
    if (CONTROLLED_ENVIRONMENT) {
      return ctx.error(
        "rule",
        "Audit logging cannot be disabled in a controlled environment"
      );
    }
    try {
      await disableAuditLog(ctx.asCaller.supabase, ctx.company.id);
    } catch (err) {
      return ctx.error("internal", "Failed to disable audit logging", err);
    }
    return { auditLogEnabled: false };
  }
});

/** A signed URL that downloads one of the company's audit log archives. */
export const getAuditArchiveDownloadUrl = defineServiceFn({
  input: z.object({ archiveId: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { archiveId }) {
    try {
      const url = await getArchiveDownloadUrl(
        ctx.asSystem.supabase,
        archiveId,
        ctx.company.id
      );
      return { url };
    } catch (err) {
      return ctx.error("internal", "Failed to generate download URL", err);
    }
  }
});

/** A Stripe billing portal session for the company, for its subscription. */
export const getBillingPortalUrl = defineServiceFn({
  input: z.object({}),
  permission: { update: "settings" },
  async run(ctx) {
    try {
      const plans = await ctx.asCaller.supabase
        .from("plan")
        .select("stripePriceId")
        .eq("userBasedPricing", true);
      const priceIds = plans.data?.map((plan) => plan.stripePriceId);
      const url = await getBillingPortalRedirectUrl({
        companyId: ctx.company.id,
        priceIds
      });
      return { url };
    } catch (err) {
      return ctx.error("internal", "Failed to access billing portal", err);
    }
  }
});

/**
 * Transfer ownership of the company group to another user.
 *
 * @remarks
 * The owner holds billing and the group's administrative settings.
 */
export const transferCompanyOwnership = defineServiceFn({
  input: z.object({ newOwnerId: z.string().min(1) }),
  permission: { update: "settings" },
  async run(ctx, { newOwnerId }) {
    const { error } = await ctx.asCaller.supabase
      .from("companyGroup")
      .update({ ownerId: newOwnerId })
      .eq("id", ctx.company.groupId);
    if (error) {
      return ctx.error("internal", "Failed to transfer ownership", error);
    }
    return { ownerId: newOwnerId };
  }
});

/**
 * Set the tags of some records of one table.
 *
 * @remarks
 * Replaces the `tags` of each record. Row-level security decides which
 * records the caller may change.
 */
export const setRecordTags = defineServiceFn({
  input: z.object({
    table: z.string().min(1),
    ids: z.array(z.string()),
    tags: z.array(z.string())
  }),
  permission: {},
  async run(ctx, { table, ids, tags }) {
    const { error } = await ctx.asCaller.supabase
      // @ts-expect-error: the table is the caller's, for any taggable record
      .from(table)
      .update(
        unchecked({
          tags,
          updatedBy: ctx.auditUserId,
          updatedAt: datetime.timestamp()
        })
      )
      .in(unchecked("id"), ids);
    if (error) return ctx.error("internal", "Failed to update tags", error);
    return { ids };
  }
});

/**
 * Set the custom field values of some records of one table.
 *
 * @remarks
 * Replaces the `customFields` of each record. Row-level security decides
 * which records the caller may change.
 */
export const setRecordCustomFields = defineServiceFn({
  input: z.object({
    table: z.string().min(1),
    ids: z.array(z.string()),
    customFields: z.record(z.string(), z.unknown())
  }),
  permission: {},
  async run(ctx, { table, ids, customFields }) {
    const { error } = await ctx.asCaller.supabase
      // @ts-expect-error: the table is the caller's, for any record with custom fields
      .from(table)
      .update(
        unchecked({
          customFields,
          updatedBy: ctx.auditUserId,
          updatedAt: datetime.timestamp()
        })
      )
      .in(unchecked("id"), ids);
    if (error) {
      return ctx.error("internal", "Failed to update custom fields", error);
    }
    return { ids };
  }
});

/**
 * Retry, re-send or skip accounting sync operations.
 *
 * @remarks
 * "Pending" queues each operation for sync again (retry, re-send);
 * "Skipped" drops it from the inbox. Each operation's transition is checked
 * against its current status, and one that cannot move is reported.
 *
 * @mcp
 */
export const transitionSyncOperations = defineServiceFn({
  input: z.object({
    ids: z
      .array(z.string().min(1))
      .min(1, { message: "No operations selected" })
      .max(500, { message: "Select at most 500 operations at once" }),
    to: z.enum(["Pending", "Skipped"])
  }),
  permission: { update: "settings" },
  async run(ctx, { ids, to }) {
    const result = await service.transitionSyncOperations(
      ctx.asCaller.supabase,
      { ids, companyId: ctx.company.id, to, userId: ctx.auditUserId }
    );
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to update sync operations",
        result.error
      );
    }
    if (result.failures.length > 0) {
      logger.warn("Sync operations were not transitioned", {
        companyId: ctx.company.id,
        to,
        failures: result.failures
      });
      return ctx.error(
        "rule",
        result.moved > 0
          ? `Updated ${result.moved} of ${result.moved + result.failures.length} sync operations`
          : "Failed to update sync operation",
        result.failures
      );
    }
    return { count: result.moved, to };
  }
});

/** Propose provider accounts for unmapped Carbon accounts, with AI. Writes nothing. */
export const suggestAccountMappings = defineServiceFn({
  input: z.object({
    accounts: z.array(
      z.object({
        id: z.string().min(1),
        number: z.string().nullable(),
        name: z.string()
      })
    ),
    providerAccounts: z.array(
      z.object({
        id: z.string().min(1),
        code: z.string().nullable().optional(),
        name: z.string().nullable().optional()
      })
    )
  }),
  permission: { update: "settings" },
  async run(ctx, { accounts, providerAccounts }) {
    const result = await suggestAccountMatchesWithAI({
      accounts,
      providerAccounts
    });
    if (result.error || !result.data) {
      return ctx.error(
        "internal",
        "Failed to suggest account mappings",
        result.error
      );
    }
    return { proposals: result.data };
  }
});

/** Map Carbon accounts to an accounting integration's accounts. */
export const saveAccountMappings = defineServiceFn({
  input: z.object({
    integrationId: z.string().min(1),
    mappings: z
      .array(accountMappingEntrySchema)
      .min(1, { message: "No account mappings to save" })
  }),
  permission: { update: "settings" },
  async run(ctx, { integrationId, mappings }) {
    const result = await upsertAccountMappings(ctx.asSystem.pg, {
      companyId: ctx.company.id,
      integration: integrationId,
      userId: ctx.auditUserId,
      mappings
    });
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to save account mappings",
        result.error
      );
    }
    return { count: mappings.length };
  }
});
/**
 * Set which Carbon dimensions ride along on the journals pushed to an accounting integration.
 *
 * @remarks
 * Each slot pairs a Carbon dimension with one of the provider's analytics
 * targets; the slots are checked against the targets the provider declares
 * and its slot limit. No slots turns dimension sync off. Unmapped values are
 * warned about or dropped.
 *
 * @mcp
 */
export const updateDimensionSync = defineServiceFn({
  input: z.object({
    integrationId: z.string().min(1),
    slots: z.array(dimensionSlotEntrySchema),
    onUnmappedDimensionValue: z.enum(["warn", "drop"])
  }),
  permission: { update: "settings" },
  async run(ctx, { integrationId, slots, onUnmappedDimensionValue }) {
    const providerTargets = await service.getProviderDimensionTargets(
      ctx.asCaller.supabase,
      ctx.company.id,
      integrationId
    );
    if (!providerTargets.supported) {
      return ctx.error(
        "rule",
        "This integration does not support dimension sync"
      );
    }
    // Clearing every slot is always allowed; validating a non-empty config
    // against a failed target fetch would reject every target as unknown.
    if (slots.length > 0 && providerTargets.targetsError) {
      return ctx.error(
        "unavailable",
        "Couldn't load the provider's dimension targets — try again"
      );
    }
    const slotErrors = validateDimensionSlots({
      slots,
      targets: providerTargets.targets,
      maxSlots: providerTargets.maxSlots ?? undefined
    });
    if (slotErrors.length > 0) {
      return ctx.error(
        "rule",
        "Invalid dimension slot configuration",
        slotErrors.join(" ")
      );
    }

    const existing = await service.integrationSettings(ctx, integrationId);
    if (!existing) {
      return ctx.error("notFound", "Failed to load integration settings");
    }
    const postingSync =
      (existing.settings.postingSync as Record<string, unknown> | undefined) ??
      {};

    // The v2 shim-marker keys are deliberately left in place: this does not
    // write the v3 sourceTypes record, so stripping them would make the
    // schema shim lose the stored v2 enabled set on the next read.
    const saved = await service.saveIntegrationMetadata(
      ctx,
      integrationId,
      existing.active ?? true,
      {
        ...existing.metadata,
        settings: {
          ...existing.settings,
          postingSync: {
            ...postingSync,
            dimensionSlots: slots,
            onUnmappedDimensionValue
          }
        }
      },
      "Failed to update dimension sync settings"
    );
    return saved ?? { integrationId };
  }
});

/** Map Carbon dimension values to an accounting integration's analytics values. */
export const saveDimensionValueMappings = defineServiceFn({
  input: z.object({
    integrationId: z.string().min(1),
    mappings: z
      .array(dimensionValueMappingEntrySchema)
      .min(1, { message: "No dimension value mappings to save" })
  }),
  permission: { update: "settings" },
  async run(ctx, { integrationId, mappings }) {
    const failures: string[] = [];
    // ponytail: one upsert per value, as the match drawer confirms a page of
    // names; a batched upsert in the engine when it confirms thousands.
    for (const mapping of mappings) {
      const result = await upsertDimensionValueMapping(ctx.asSystem.pg, {
        companyId: ctx.company.id,
        integration: integrationId,
        ...mapping,
        userId: ctx.auditUserId
      });
      if (result.error) failures.push(result.error);
    }
    if (failures.length > 0) {
      const succeeded = mappings.length - failures.length;
      return ctx.error(
        succeeded > 0 ? "rule" : "internal",
        succeeded > 0
          ? `Saved ${succeeded} of ${mappings.length} dimension value mappings`
          : mappings.length === 1
            ? "Failed to save dimension value mapping"
            : "Failed to save dimension value mappings",
        failures[0]
      );
    }
    return { count: mappings.length };
  }
});

/**
 * Turn an accounting integration's sync on or off.
 *
 * @remarks
 * A new connection starts with sync off. Turning it on is refused until
 * every required account is mapped, so the first push cannot park a wall of
 * unmapped-account warnings.
 *
 * @mcp
 */
export const setIntegrationSyncEnabled = defineServiceFn({
  input: z.object({
    integrationId: z.string().min(1),
    syncEnabled: z.boolean()
  }),
  permission: { update: "settings" },
  async run(ctx, { integrationId, syncEnabled }) {
    const existing = await service.integrationSettings(ctx, integrationId);
    if (!existing?.active) {
      return ctx.error("notFound", "Failed to load integration settings");
    }

    if (syncEnabled) {
      const unmapped = await getUnmappedRequiredAccounts(ctx.asSystem.pg, {
        companyId: ctx.company.id,
        integration: integrationId
      });
      if (unmapped.error || !unmapped.data) {
        return ctx.error(
          "internal",
          "Failed to check the account mapping",
          unmapped.error
        );
      }
      if (unmapped.data.length > 0) {
        return ctx.error(
          "rule",
          `Map the remaining ${unmapped.data.length} required account${
            unmapped.data.length === 1 ? "" : "s"
          } before turning on sync`
        );
      }
    }

    const saved = await service.saveIntegrationMetadata(
      ctx,
      integrationId,
      existing.active,
      {
        ...existing.metadata,
        settings: { ...existing.settings, syncEnabled }
      },
      "Failed to update sync"
    );
    return saved ?? { syncEnabled };
  }
});

/**
 * Set how an accounting integration receives postings.
 *
 * @remarks
 * Posting sync is always on. Each journal-represented source type except
 * Manual is sent, individually or as a daily summary (`sourceTypeConfigs`:
 * "<source type>|individual" or "|daily-summary"; an unlisted type takes its
 * default). Receivables, payables, credit memos and supplier credits each go
 * as documents, as journals or not at all. A posting into a locked provider
 * period is parked or redated, and `lockDate` is the provider's lock date.
 * Keys this form does not own (the weekly reconciliation's) are kept.
 *
 * @mcp
 */
export const updatePostingSync = defineServiceFn({
  input: z.object({
    integrationId: z.string().min(1),
    sourceTypeConfigs: z.array(
      z
        .string()
        .regex(
          /^[^|]+\|(individual|daily-summary)$/,
          "Malformed source-type config"
        )
    ),
    familyAr: z.enum(["documents", "journals", "none"]),
    familyAp: z.enum(["documents", "journals", "none"]),
    familyCreditMemo: z.enum(["documents", "journals", "none"]),
    familySupplierCredit: z.enum(["documents", "journals", "none"]),
    periodLockPolicy: z.enum(["park", "redate"]),
    lockDate: z.string().optional()
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    const granularityBySourceType = new Map(
      input.sourceTypeConfigs.map((config) => {
        const separator = config.lastIndexOf("|");
        return [
          config.slice(0, separator),
          config.slice(separator + 1) as "individual" | "daily-summary"
        ] as const;
      })
    );
    const sourceTypes: Record<
      string,
      { enabled: boolean; granularity: "individual" | "daily-summary" }
    > = {};
    for (const sourceType of JOURNAL_ENTRY_SOURCE_TYPES) {
      if (POSTING_POLICY[sourceType].representation !== "journal") continue;
      if (sourceType === "Manual") continue;
      sourceTypes[sourceType] = {
        enabled: true,
        granularity:
          granularityBySourceType.get(sourceType) ??
          POSTING_POLICY[sourceType].defaultGranularity
      };
    }

    const existing = await service.integrationSettings(
      ctx,
      input.integrationId
    );
    if (!existing) {
      return ctx.error("notFound", "Failed to load integration settings");
    }

    // Saving writes the v3 shape: the v2 shim markers (includeManual,
    // consolidation, the legacy sourceTypes array) and the old master
    // `enabled` are dropped, or the schema shim would read the fragment as v2.
    const {
      includeManual: _includeManual,
      consolidation: _consolidation,
      sourceTypes: _legacySourceTypes,
      enabled: _enabled,
      ...postingSync
    } = (existing.settings.postingSync as
      | Record<string, unknown>
      | undefined) ?? {};

    const saved = await service.saveIntegrationMetadata(
      ctx,
      input.integrationId,
      existing.active ?? true,
      {
        ...existing.metadata,
        settings: {
          ...existing.settings,
          postingSync: {
            ...postingSync,
            families: {
              ar: input.familyAr,
              ap: input.familyAp,
              creditMemo: input.familyCreditMemo,
              supplierCredit: input.familySupplierCredit
            },
            sourceTypes,
            periodLockPolicy: input.periodLockPolicy,
            ...(input.lockDate ? { lockDate: input.lockDate } : {})
          }
        }
      },
      "Failed to update posting sync settings"
    );
    return saved ?? { integrationId: input.integrationId };
  }
});

/**
 * Map an OEE integration's device to a work center, or unmap it.
 *
 * @remarks
 * Only a station the current connection reports can be mapped: a list read
 * before the API key changed could name a station the provider does not
 * have, whose mapping would never sync. The stored name, site and time zone
 * are the provider's. No work center unmaps the device. OEE integrations are
 * a commercial feature.
 */
export const saveOeeDeviceMapping = defineServiceFn({
  input: z.object({
    integrationId: z.string().min(1),
    externalDeviceId: z.string().min(1),
    deviceName: z.string().min(1),
    workCenterId: z.string().optional()
  }),
  permission: { update: "settings" },
  async run(
    ctx,
    { integrationId, externalDeviceId, deviceName, workCenterId }
  ) {
    let device: OeeDevice | undefined;
    if (workCenterId) {
      const provider = await service.listOeeDevices(
        ctx.company.id,
        integrationId
      );
      device = provider.devices.find(
        (candidate) => candidate.externalDeviceId === externalDeviceId
      );
      if (!device) {
        return ctx.error(
          "rule",
          `Failed to save device mapping: ${
            provider.error ?? `${deviceName} is not a station of this provider`
          }`
        );
      }
    }

    let result: { error: string | null };
    try {
      result =
        workCenterId && device
          ? await upsertWorkCenterDevice(
              ctx.asCaller.supabase,
              ctx.asSystem.pg,
              {
                companyId: ctx.company.id,
                userId: ctx.auditUserId,
                integration: integrationId,
                externalDeviceId,
                externalSiteId: device.externalSiteId,
                siteTimezone: device.siteTimezone,
                deviceName: device.name,
                workCenterId
              }
            )
          : await deleteWorkCenterDevice(
              ctx.asCaller.supabase,
              ctx.asSystem.pg,
              {
                companyId: ctx.company.id,
                userId: ctx.auditUserId,
                integration: integrationId,
                externalDeviceId
              }
            );
    } catch (err) {
      if (!(err instanceof EntitlementError)) throw err;
      return ctx.error(
        "entitlement",
        `Failed to save device mapping: ${err.message}`
      );
    }
    if (result.error) {
      return ctx.error(
        "rule",
        `Failed to save device mapping: ${result.error}`
      );
    }
    return { externalDeviceId, workCenterId: workCenterId ?? null };
  }
});
/**
 * Get accounts payable billing address
 *
 * @mcp read
 */
export const getAccountsPayableBillingAddress = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getAccountsPayableBillingAddress(
        ctx.asCaller.supabase,
        ctx.company.id
      )
    );
  }
});

/**
 * Get accounts receivable billing address
 *
 * @mcp read
 */
export const getAccountsReceivableBillingAddress = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getAccountsReceivableBillingAddress(
        ctx.asCaller.supabase,
        ctx.company.id
      )
    );
  }
});

/**
 * Get api keys
 *
 * @mcp
 */
export const getApiKeys = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { update: "users" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getApiKeys(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * List the companies the caller belongs to, with their logo URLs.
 *
 * @mcp read
 */
export const getCompanies = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getCompanies(ctx.asCaller.supabase, ctx.auditUserId)
    );
  }
});

/**
 * The companies a user can enter in the ERP
 *
 * @mcp read
 */
export const getEmployeeCompanies = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getEmployeeCompanies(ctx.asCaller.supabase, ctx.auditUserId)
    );
  }
});

/**
 * Get industries
 *
 * @mcp read
 */
export const getIndustries = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(ctx, await service.getIndustries(ctx.asCaller.supabase));
  }
});

/**
 * Get company
 *
 * @mcp read
 */
export const getCompany = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getCompany(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Get company settings
 *
 * @mcp read
 */
export const getCompanySettings = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getCompanySettings(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Get config
 *
 * @mcp read
 */
export const getConfig = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(ctx, await service.getConfig(ctx.asCaller.supabase));
  }
});

/**
 * Get current sequence
 *
 * @mcp read
 */
export const getCurrentSequence = defineServiceFn({
  input: z.looseObject({ table: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getCurrentSequence(
        ctx.asCaller.supabase,
        input.table as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get custom field
 *
 * @mcp read
 */
export const getCustomField = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getCustomField(ctx.asCaller.supabase, input.id as never)
    );
  }
});

/**
 * Get custom fields
 *
 * @mcp read
 */
export const getCustomFields = defineServiceFn({
  input: z.looseObject({ table: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getCustomFields(
        ctx.asCaller.supabase,
        input.table as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get custom fields tables
 *
 * @mcp read
 */
export const getCustomFieldsTables = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getCustomFieldsTables(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get integration
 *
 * @mcp read
 */
export const getIntegration = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getIntegration(
        ctx.asCaller.supabase,
        input.id as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get kanban output setting
 *
 * @mcp read
 */
export const getKanbanOutputSetting = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getKanbanOutputSetting(
        ctx.asCaller.supabase,
        ctx.company.id
      )
    );
  }
});

/**
 * Takes the next number of a sequence, which advances it
 *
 * @mcp
 */
export const getNextSequence = defineServiceFn({
  input: z.looseObject({ table: z.string() }),
  permission: { update: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getNextSequence(
        ctx.asCaller.supabase,
        input.table as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get plans
 *
 * @mcp read
 */
export const getPlans = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(ctx, await service.getPlans(ctx.asCaller.supabase));
  }
});

/**
 * Get sequence
 *
 * @mcp read
 */
export const getSequence = defineServiceFn({
  input: z.looseObject({ table: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSequence(
        ctx.asCaller.supabase,
        input.table as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get sequences
 *
 * @mcp read
 */
export const getSequences = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getSequences(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get sequences list
 *
 * @mcp read
 */
export const getSequencesList = defineServiceFn({
  input: z.looseObject({ table: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSequencesList(
        ctx.asCaller.supabase,
        input.table as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get item serial sequences
 *
 * @mcp read
 */
export const getItemSerialSequences = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getItemSerialSequences(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get item serial sequence
 *
 * @mcp read
 */
export const getItemSerialSequence = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getItemSerialSequence(
        ctx.asCaller.supabase,
        input.id as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Create a item serial sequence
 *
 * @remarks
 * Upsert item serial sequence
 *
 * @mcp
 */
export const createItemSerialSequence = defineServiceFn({
  input: z.looseObject({
    itemId: z.string().min(1),
    prefix: z.string().optional(),
    suffix: z.string().optional(),
    next: z.number().min(0),
    step: z.number().min(1),
    size: z.number().min(1).max(20),
    serialNumberTiming: z
      .enum(serialNumberTimings)
      .nullable()
      .optional()
      .describe(
        "When this item's units draw their serial numbers. Omit or null to follow the company setting."
      ),
    id: z
      .string()
      .describe("Send to update that record; omit to create a new one.")
      .optional()
  }),
  permission: { create: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertItemSerialSequence(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a item serial sequence
 *
 * @remarks
 * Upsert item serial sequence
 *
 * @mcp
 */
export const updateItemSerialSequence = defineServiceFn({
  input: z
    .looseObject({
      itemId: z.string().min(1),
      prefix: z.string().optional(),
      suffix: z.string().optional(),
      next: z.number().min(0),
      step: z.number().min(1),
      size: z.number().min(1).max(20),
      serialNumberTiming: z
        .enum(serialNumberTimings)
        .nullable()
        .optional()
        .describe(
          "When this item's units draw their serial numbers. Null follows the company setting. Omitted, a new sequence follows the company setting and an update keeps the current value."
        ),
      id: z
        .string()
        .describe("Send to update that record; omit to create a new one.")
        .optional()
    })
    .required({ id: true }),
  permission: { update: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertItemSerialSequence(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Delete item serial sequence
 *
 * @mcp destructive
 */
export const deleteItemSerialSequence = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { delete: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteItemSerialSequence(
        ctx.asCaller.supabase,
        input.id as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Get subsidiaries
 *
 * @mcp read
 */
export const getSubsidiaries = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getSubsidiaries(ctx.asCaller.supabase, ctx.company.groupId)
    );
  }
});

/**
 * Get subsidiary
 *
 * @mcp read
 */
export const getSubsidiary = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getSubsidiary(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Get terms
 *
 * @mcp read
 */
export const getTerms = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getTerms(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Get document template
 *
 * @mcp read
 */
export const getDocumentTemplate = defineServiceFn({
  input: z.looseObject({
    documentType: z.enum([
      "purchaseOrder",
      "salesOrder",
      "stockTransfer",
      "salesInvoice",
      "quote",
      "purchaseReturnOrder",
      "salesReturnOrder",
      "issue",
      "packingSlip",
      "jobTraveler",
      "trackingLabel"
    ])
  }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getDocumentTemplate(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.documentType as never
      )
    );
  }
});

/**
 * Load a stored document template as a `DocumentTemplate | null` ready to pass to a PDF (which runs it through `resolveTemplate`)
 *
 * @mcp read
 */
export const getDocumentTemplateConfig = defineServiceFn({
  input: z.looseObject({
    documentType: z.enum([
      "purchaseOrder",
      "salesOrder",
      "stockTransfer",
      "salesInvoice",
      "quote",
      "purchaseReturnOrder",
      "salesReturnOrder",
      "issue",
      "packingSlip",
      "jobTraveler",
      "trackingLabel"
    ])
  }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return await service.getDocumentTemplateConfig(
      ctx.asCaller.supabase,
      ctx.company.id,
      input.documentType as never
    );
  }
});

/**
 * Get document sections
 *
 * @mcp read
 */
export const getDocumentSections = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(
      ctx,
      await service.getDocumentSections(ctx.asCaller.supabase, ctx.company.id)
    );
  }
});

/**
 * Fetch the given section ids and return them keyed by id for rendering
 *
 * @mcp
 */
export const resolveSections = defineServiceFn({
  input: z.looseObject({ ids: z.array(z.string()) }),
  permission: { update: "settings" },
  async run(ctx, input) {
    return await service.resolveSections(
      ctx.asCaller.supabase,
      ctx.company.id,
      payload(ctx, input.ids).build() as never
    );
  }
});

/**
 * Get webhook
 *
 * @mcp read
 */
export const getWebhook = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getWebhook(ctx.asCaller.supabase, input.id as never)
    );
  }
});

/**
 * Get webhooks
 *
 * @mcp read
 */
export const getWebhooks = defineServiceFn({
  input: z.looseObject({
    limit: z
      .number()
      .int()
      .describe("Rows per page. Left out, the read is not paged.")
      .optional(),
    offset: z.number().int().default(0),
    search: z.string().nullable().optional()
  }),
  permission: { view: "settings" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getWebhooks(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get webhook tables
 *
 * @mcp read
 */
export const getWebhookTables = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "settings" },
  async run(ctx) {
    return unwrap(ctx, await service.getWebhookTables(ctx.asCaller.supabase));
  }
});

/**
 * Update sequence
 *
 * @mcp
 */
export const updateSequence = defineServiceFn({
  input: z.looseObject({
    table: z.string(),
    sequence: z.looseObject({
      table: z.string().min(1).optional(),
      prefix: z.string().optional(),
      suffix: z.string().optional(),
      next: z.number().min(0).optional(),
      step: z.number().min(1).optional(),
      size: z.number().min(1).max(20).optional()
    })
  }),
  permission: { update: "settings" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSequence(
        ctx.asCaller.supabase,
        input.table as never,
        ctx.company.id,
        payload(ctx, input.sequence).forUpdate() as never
      )
    );
  }
});

/**
 * Detach an item from the Onshape panel
 *
 * @remarks
 * Removes the item's `onshape-v2` link. The item keeps its model, documents
 * and fields. A sync connection's `onshape` row is bill-of-materials import
 * bookkeeping that the BoM Explorer reads, so it is never removed here.
 */
export const detachOnshapeItem = defineServiceFn({
  input: z.object({ itemId: z.string().min(1) }),
  permission: { update: "parts" },
  async run(ctx, { itemId }) {
    const removed = await ctx.asSystem.supabase
      .from("externalIntegrationMapping")
      .delete()
      .eq("companyId", ctx.company.id)
      .eq("integration", ONSHAPE_V2_INTEGRATION_ID)
      .eq("entityType", "item")
      .eq("entityId", itemId)
      .select("id");
    if (removed.error) {
      return ctx.error(
        "internal",
        "Failed to detach from Onshape",
        removed.error
      );
    }
    if (removed.data.length === 0) {
      return ctx.error("notFound", "This item is not linked to Onshape");
    }
    return { itemId };
  }
});

/**
 * Save the Onshape panel's property map
 *
 * @remarks
 * Replaces the property map, the description modes and the push defaults.
 * Answers in the panel's own reply shape.
 */
export const saveOnshapePropertyMap = defineServiceFn({
  input: service.onshapePropertyMapInput,
  permission: { update: "settings" },
  run: (ctx, input) => service.saveOnshapePropertyMap(ctx, input)
});

/**
 * Push reviewed Onshape parts
 *
 * @remarks
 * Applies a part review from the Onshape panel: creates or adopts items,
 * links them, and queues their model exports. Answers in the panel's own
 * reply shape.
 */
export const pushOnshapePart = defineServiceFn({
  input: service.onshapePartPushInput,
  permission: { create: "parts", update: "parts" },
  run: (ctx, input) => service.pushOnshapePart(ctx, input)
});

/**
 * Push a reviewed Onshape assembly
 *
 * @remarks
 * Applies an assembly review from the Onshape panel: items, bill of material
 * lines per method, links and the model export. Re-pushing replaces the lines
 * an earlier push wrote. Answers in the panel's own reply shape.
 */
export const pushOnshapeAssembly = defineServiceFn({
  input: service.onshapeAssemblyPushInput,
  permission: { create: "parts", update: "parts", delete: "parts" },
  run: (ctx, input) => service.pushOnshapeAssembly(ctx, input)
});

/**
 * Push a reviewed Onshape release
 *
 * @remarks
 * Applies a release review from the Onshape panel. Carbon's state when it
 * applies outranks the review. Answers in the panel's own reply shape.
 */
export const pushOnshapeRelease = defineServiceFn({
  input: service.onshapeReleasePushInput,
  permission: { create: "parts", update: "parts", delete: "parts" },
  run: (ctx, input) => service.pushOnshapeRelease(ctx, input)
});