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.

203 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 { CarbonError, defineServiceFn } from "@carbon/api/service-fn.server";
import { paged, payload, unwrap } from "@carbon/api/service-tools.server";
import {
  type Database,
  fetchAllByIds,
  getCompanyTimeZone,
  type Json
} from "@carbon/database";
import {
  convertUnitPrice,
  supplierPartCurrency
} from "@carbon/database/supplier-part-price";
import { approvalDecisionValidator } from "@carbon/ee/approvals";
import {
  decideApprovalRequest,
  openApprovalRequests
} from "@carbon/ee/approvals/document.server";
import {
  approveRequest,
  canApproveRequest,
  getApprovalRuleByAmount,
  getApproverUserIdsForRule,
  getLatestApprovalRequestForDocument,
  getLowerTierApproverUserIds,
  isApprovalRequired,
  rejectRequest
} from "@carbon/ee/approvals.server";
import { storage, storedDocumentPdfName } from "@carbon/files";
import { trigger } from "@carbon/jobs";
import { checkPartyContactRequirement } from "@carbon/lib/party-contact.server";
import { trackWorkEvent } from "@carbon/lib/telemetry";
import { getLogger } from "@carbon/logger";
import { NotificationEvent } from "@carbon/notifications";
import type { JSONContent } from "@carbon/react";
import {
  applyRate,
  async,
  datetime,
  deriveRate,
  escapeHTMLChars,
  groupBy,
  PO_EMAIL_ATTACHMENT_LIMIT_MB,
  SCALE,
  sanitize,
  taxableBase,
  tiptapToHTML,
  unchecked
} from "@carbon/utils";
import { type CalendarDate, parseDate } from "@internationalized/date";
import { z } from "zod";
import { getExchangeRate } from "~/modules/accounting/accounting.service";
import { upsertDocument } from "~/modules/documents/documents.service";
import {
  assignPlanningActions,
  dismissPlanningActions,
  getPlanningActionsByIds,
  reopenDismissedPlanningActions,
  runMRP,
  settleNewSupplyPlanningActions
} from "~/modules/production/production.service";
import {
  getCompany,
  getCompanySettings
} from "~/modules/settings/settings.service";
import { incoterms, optionalTiptapDoc } from "~/modules/shared/shared.models";
import {
  getLocationTimeZone,
  invokePosting,
  isActiveCompanyEmployee,
  refuseUnlessOwned
} from "~/modules/shared/shared.service";
import { getUser } from "~/modules/users/users.service";
import { ERP_URL, path } from "~/utils/path";
import { fromServerFn } from "../shared/shared.service";
import {
  canCreatePurchaseOrderRevision,
  findPlanningPurchaseOrder,
  isIsoDate,
  isPurchaseOrderDateField,
  isPurchaseOrderEditableFromPlanning,
  isPurchaseOrderLocked,
  isPurchaseReturnOrderLocked,
  isRfqLocked,
  isSupplierQuoteLocked,
  leaseClassificationValidator,
  leaseModifyValidator,
  leasePurchaseValidator,
  leaseTerminateValidator,
  lockedReturnLineField,
  PURCHASE_ORDER_REOPEN_STATUSES,
  plannedOrderValidator,
  planningPurchaseOrderWeek,
  purchaseOrderDeleteRefusal,
  purchaseOrderLineDateFields,
  purchaseOrderLineDateRefusal,
  purchaseOrderPromisedDateRefusal,
  purchaseOrderStatusType,
  purchaseReturnOrderLineValidator,
  purchasingRfqFinalizeValidator,
  purchasingRfqValidator,
  selectedLineSchema,
  splitRfqModelAttachments,
  supplierQuoteFinalizeValidator,
  taxPairForQuantity
} from "./purchasing.models";
import { renderPurchaseReturnOrderPdf } from "./purchasing.pdf";
import * as service from "./purchasing.service";
import type { PurchaseOrderStatus } from "./types";

// ── Operations ──────────────────────────────────────────────────────────────
// `defineServiceFn` operations: what the routes, the API and MCP call, so each
// holds every check its button made. Listed by entity in `index.server.ts`.

const logger = getLogger("erp", "purchasing");

/** How long a model link in an RFQ email works: a supplier may open it days later. */
const RFQ_MODEL_LINK_SECONDS = 7 * 24 * 60 * 60;

/** Custom field values, as `setCustomFields` reads them from a form. */
const customFieldsInput = z.record(
  z.string(),
  z.union([z.string(), z.number(), z.boolean()])
);
// ── RFQs ────────────────────────────────────────────────────────────────────

/**
 * Create a request for quotation.
 *
 * @remarks
 * Creates the RFQ, numbered from the `purchasingRfq` sequence unless `rfqId`
 * is given, then invites `supplierIds`. The two writes are separate: when the
 * suppliers cannot be saved, the RFQ exists without them and the error says
 * so.
 *
 * @mcp
 */

export const createPurchasingRfq = defineServiceFn({
  input: purchasingRfqValidator
    .omit({ id: true })
    .extend({ customFields: customFieldsInput.optional() }),
  permission: { create: "purchasing" },

  async run(ctx, { supplierIds, ...rfq }) {
    const companyId = ctx.company.id;
    const created = await service.insertPurchasingRFQ(ctx.asCaller.supabase, {
      ...rfq,
      rfqId: rfq.rfqId || undefined,
      companyId,
      createdBy: ctx.auditUserId
    });
    if (created.error || !created.data) {
      return ctx.error("internal", "Failed to insert RFQ", created.error);
    }

    const suppliers = await service.upsertPurchasingRFQSuppliers(
      ctx.asCaller.supabase,
      created.data.id,
      supplierIds,
      companyId,
      ctx.auditUserId
    );
    if (suppliers.error) {
      return ctx.error(
        "internal",
        "Failed to assign suppliers",
        suppliers.error
      );
    }
    return { id: created.data.id, rfqId: created.data.rfqId };
  }
});

const rfqDateFields = [
  "employeeId",
  "expirationDate",
  "locationId",
  "rfqDate"
] as const;

/**
 * Change one field of RFQs.
 *
 * @remarks
 * The RFQ properties panel's edit. `employeeId`, `expirationDate`,
 * `locationId` and `rfqDate` take one value (null clears it); `supplierIds`
 * replaces the invited suppliers of every RFQ. Refused when any of the RFQs is
 * locked (Requested or Closed).
 *
 * @mcp
 */
export const updatePurchasingRfqs = defineServiceFn({
  input: z.discriminatedUnion("field", [
    z.object({
      ids: z.array(z.string()).min(1),
      field: z.enum(rfqDateFields),
      value: z.string().nullable()
    }),
    z.object({
      ids: z.array(z.string()).min(1),
      field: z.literal("supplierIds"),
      value: z.array(z.string())
    })
  ]),
  permission: { update: "purchasing" },

  async run(ctx, input) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;
    const statuses = await service.statusesOf(ctx, "purchasingRfq", input.ids);
    if (statuses instanceof CarbonError) return statuses;
    if (statuses.some(isRfqLocked)) {
      return ctx.error("rule", "Cannot modify a locked RFQ.");
    }

    if (input.field === "supplierIds") {
      const removed = await client
        .from("purchasingRfqSupplier")
        .delete()
        .in("purchasingRfqId", input.ids)
        .eq("companyId", companyId);
      if (removed.error) {
        return ctx.error(
          "internal",
          "Failed to update suppliers",
          removed.error
        );
      }
      if (input.value.length === 0) return { ids: input.ids };
      const added = await client.from("purchasingRfqSupplier").insert(
        input.ids.flatMap((purchasingRfqId) =>
          input.value.map((supplierId) => ({
            purchasingRfqId,
            supplierId,
            companyId,
            createdBy: ctx.auditUserId
          }))
        )
      );
      if (added.error) {
        return ctx.error("internal", "Failed to update suppliers", added.error);
      }
      return { ids: input.ids };
    }

    const update = await client
      .from("purchasingRfq")
      .update(
        unchecked({
          [input.field]: input.value || null,
          updatedBy: ctx.auditUserId,
          updatedAt: datetime.timestamp()
        })
      )
      .in("id", input.ids)
      .eq("companyId", companyId);
    if (update.error) {
      return ctx.error("internal", "Failed to update the RFQ", update.error);
    }
    return { ids: input.ids };
  }
});

/**
 * Cancel an RFQ.
 *
 * @remarks
 * Closes the RFQ, clears its assignee, and cancels every supplier quote it
 * raised. A failure to cancel the quotes is logged; the RFQ stays Closed.
 *
 * @mcp destructive
 */
export const cancelPurchasingRfq = defineServiceFn({
  input: z.object({ rfqId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { rfqId }) {
    const client = ctx.asCaller.supabase;
    const update = await service.updatePurchasingRFQStatus(client, {
      id: rfqId,
      status: "Closed",
      assignee: null,
      updatedBy: ctx.auditUserId
    });
    if (update.error) {
      return ctx.error("internal", "Failed to cancel RFQ", update.error);
    }

    const linked = await service.getLinkedSupplierQuotes(client, rfqId);
    const quoteIds = (linked.data ?? []).map((link) => link.supplierQuoteId);
    if (quoteIds.length > 0) {
      const quotes = await client
        .from("supplierQuote")
        .update({ status: "Cancelled", updatedBy: ctx.auditUserId })
        .in("id", quoteIds)
        .eq("companyId", ctx.company.id);
      if (quotes.error) {
        logger.error("Failed to cancel the RFQ's supplier quotes", {
          companyId: ctx.company.id,
          rfqId,
          error: quotes.error
        });
      }
    }
    return { rfqId };
  }
});

/**
 * Send an RFQ to its suppliers.
 *
 * @remarks
 * Creates one supplier quote per invited supplier, with the RFQ's lines and a
 * share link, and marks the RFQ Requested, in one transaction
 * (`finalize-purchasing-rfq`, which refuses an RFQ that is not Draft). Then,
 * for each supplier with a `contactId`, emails the contact the quote's link
 * with the RFQ's documents and internal notes attached; a failed email is
 * logged and the rest still go. Refused when the RFQ has no lines.
 *
 * @mcp
 */
export const finalizePurchasingRfqAndNotify = defineServiceFn({
  input: purchasingRfqFinalizeValidator.extend({ rfqId: z.string() }),
  permission: { create: "purchasing" },

  async run(ctx, { rfqId, suppliers }) {
    const client = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;

    const owned = await refuseUnlessOwned(ctx, "purchasingRfq", { id: rfqId });
    if (owned) return owned;

    const [rfq, lines] = await Promise.all([
      service.getPurchasingRFQ(client, rfqId),
      service.getPurchasingRFQLines(client, rfqId)
    ]);
    if (rfq.error)
      return ctx.error("internal", "Failed to load RFQ", rfq.error);
    if (lines.error) {
      return ctx.error("internal", "Failed to load RFQ lines", lines.error);
    }
    if ((lines.data ?? []).length === 0) {
      return ctx.error("rule", "No line items found for this RFQ");
    }

    const [company, user] = await Promise.all([
      getCompany(client, companyId),
      getUser(client, userId)
    ]);

    const finalize = await invokePosting(
      ctx,
      "finalize-purchasing-rfq",
      { rfqId },
      service.finalizePurchasingRfq
    );
    if (finalize.error) {
      return fromServerFn(
        ctx,
        finalize.error,
        "Failed to create supplier quotes"
      );
    }
    const quotes = finalize.data.quotes;

    const contactIdBySupplier = new Map(
      suppliers.flatMap((s) =>
        s.contactId ? [[s.supplierId, s.contactId] as const] : []
      )
    );
    const contacts = contactIdBySupplier.size
      ? await client
          .from("supplierContact")
          .select("id, contact(email, firstName)")
          .in("id", [...contactIdBySupplier.values()])
          .eq("companyId", companyId)
      : null;
    const contactById = new Map(
      (contacts?.data ?? []).map((row) => [row.id, row.contact])
    );
    const emails = quotes.flatMap((quote) => {
      const contactId = contactIdBySupplier.get(quote.supplierId);
      const contact = contactId ? contactById.get(contactId) : undefined;
      return contact?.email
        ? [
            {
              to: contact.email,
              firstName: contact.firstName ?? "there",
              quoteReadableId: quote.supplierQuoteId,
              externalLinkId: quote.externalLinkId
            }
          ]
        : [];
    });

    if (emails.length > 0 && company.data && user.data) {
      const attachments = [
        ...(await service.interactionAttachments(client, companyId, rfqId)),
        ...(await service.getSupplierInteractionLineAttachments(
          client,
          companyId,
          (lines.data ?? []).flatMap((line) => (line.id ? [line.id] : []))
        ))
      ];
      // Each part's original CAD file: attached while the email stays under the
      // limit, a download link past it.
      const models = await service.getItemModelFiles(
        client,
        ctx.asSystem.pg,
        companyId,
        [
          ...new Set(
            (lines.data ?? []).flatMap((line) =>
              line.itemId ? [line.itemId] : []
            )
          )
        ]
      );
      const documentBytes = attachments.reduce(
        (sum, file) => sum + (file.size ?? 0),
        0
      );
      const split = splitRfqModelAttachments(
        models,
        PO_EMAIL_ATTACHMENT_LIMIT_MB * 1024 * 1024 - documentBytes
      );
      // A model whose attachment link could not be signed goes as a link; one
      // with no link either is named, so the supplier knows to ask for it.
      const attachSigned = await async.map(split.attach, async (model) => ({
        model,
        url: await service.signOriginalModelFile(client, companyId, model, 3600)
      }));
      const modelAttachments = attachSigned.flatMap(({ model, url }) =>
        url ? [{ filename: model.filename, path: url }] : []
      );
      const signedLinks = await async.map(
        [
          ...split.link,
          ...attachSigned.flatMap(({ model, url }) => (url ? [] : [model]))
        ],
        async (model) => ({
          model,
          url: await service.signOriginalModelFile(
            client,
            companyId,
            model,
            RFQ_MODEL_LINK_SECONDS
          )
        })
      );
      const modelLinks = signedLinks.flatMap(({ model, url }) =>
        url ? [{ filename: model.filename, url }] : []
      );
      const missingModels = signedLinks.flatMap(({ model, url }) =>
        url ? [] : [model.filename]
      );
      const missingHtml = missingModels.length
        ? `<br><br>These models could not be included; reply to ask for them: ${missingModels
            .map(escapeHTMLChars)
            .join(", ")}`
        : "";
      const missingText = missingModels.length
        ? `\n\nThese models could not be included; reply to ask for them: ${missingModels.join(", ")}`
        : "";
      const modelLinksHtml = modelLinks.length
        ? `<br><br>Models too large to attach (links valid for 7 days):<br>${modelLinks
            .map(
              (model) =>
                `<a href="${escapeHTMLChars(model.url)}">${escapeHTMLChars(model.filename)}</a>`
            )
            .join("<br>")}${missingHtml}`
        : missingHtml;
      const modelLinksText = modelLinks.length
        ? `\n\nModels too large to attach (links valid for 7 days):\n${modelLinks
            .map((model) => `${model.filename}: ${model.url}`)
            .join("\n")}${missingText}`
        : missingText;
      const notesHtml = tiptapToHTML(
        (rfq.data?.internalNotes ?? {}) as JSONContent
      );

      for (const email of emails) {
        try {
          const link = `${ERP_URL}${path.to.externalSupplierQuote(email.externalLinkId)}`;
          const body = `Hey ${email.firstName},\n\nPlease provide pricing and lead time(s) for the linked quote:`;
          const signature = `Thanks,\n${user.data.firstName} ${user.data.lastName}\n${company.data.name}`;
          await trigger("send-email", {
            document: true,
            to: [user.data.email, email.to],
            from: user.data.email,
            subject: `Supplier Quote ${email.quoteReadableId} from ${company.data.name}`,
            html: [
              body.replace(/\n/g, "<br>"),
              `<br><a href="${link}">${link}</a>`,
              modelLinksHtml,
              notesHtml ? `<br><br>${notesHtml}` : "",
              `<br><br>${signature.replace(/\n/g, "<br>")}`
            ].join(""),
            text: `${body}\n\n${link}${modelLinksText}\n\n${signature}`,
            attachments: [
              ...attachments.map(({ filename, path }) => ({ filename, path })),
              ...modelAttachments
            ],
            companyId
          });
        } catch (err) {
          logger.error("Failed to send email", { error: err });
        }
      }
    }

    return { quotesCreated: quotes.length, emailsSent: emails.length };
  }
});

// ── Supplier quotes ─────────────────────────────────────────────────────────

const supplierQuoteTextFields = [
  "supplierContactId",
  "supplierLocationId",
  "supplierReference",
  "quotedDate"
] as const;

/**
 * Change one field of supplier quotes.
 *
 * @remarks
 * The supplier quote properties panel's edit; `value` null clears the field.
 * A new `supplierId` on one quote takes the supplier's currency. A new
 * `currencyCode` takes today's exchange rate (refused when there is none).
 * A new `expirationDate` (`YYYY-MM-DD`) sets the quote Expired when it is
 * before today on the company's calendar, else Active. Refused when any of
 * the quotes is locked.
 *
 * @mcp
 */
export const updateSupplierQuotes = defineServiceFn({
  input: z.object({
    ids: z.array(z.string()).min(1),
    field: z.enum([
      "supplierId",
      "currencyCode",
      "expirationDate",
      ...supplierQuoteTextFields
    ]),
    value: z.string().nullable()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { ids, field, value }) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;
    const statuses = await service.statusesOf(ctx, "supplierQuote", ids);
    if (statuses instanceof CarbonError) return statuses;
    if (statuses.some(isSupplierQuoteLocked)) {
      return ctx.error(
        "rule",
        "Cannot modify a locked supplier quote. Reopen it first."
      );
    }

    const write = (
      patch: Database["public"]["Tables"]["supplierQuote"]["Update"]
    ) =>
      client
        .from("supplierQuote")
        .update({
          ...patch,
          updatedBy: ctx.auditUserId,
          updatedAt: datetime.timestamp()
        })
        .in("id", ids)
        .eq("companyId", companyId);

    let patch: Database["public"]["Tables"]["supplierQuote"]["Update"];
    if (field === "supplierId") {
      patch = { supplierId: value ?? undefined };
      if (value && ids.length === 1) {
        const supplier = await client
          .from("supplier")
          .select("currencyCode")
          .eq("id", value)
          .single();
        if (supplier.data?.currencyCode) {
          patch.currencyCode = supplier.data.currencyCode;
        }
      }
    } else if (field === "currencyCode" && value) {
      const rate = await getExchangeRate(client, companyId, value);
      if (rate.error) {
        return ctx.error("rule", rate.error.message, rate.error);
      }
      patch = { currencyCode: value, exchangeRate: rate.data };
    } else if (field === "expirationDate") {
      let expirationDate: CalendarDate | null = null;
      if (value) {
        try {
          expirationDate = parseDate(value);
        } catch {
          return ctx.error("validation", "Invalid expiration date");
        }
      }
      // Expiry is judged on the company's calendar — one set of books, one
      // "today" — not the server's or the editing user's.
      const today = datetime.today(await getCompanyTimeZone(client, companyId));
      patch = {
        status:
          expirationDate && today.compare(expirationDate) > 0
            ? "Expired"
            : "Active",
        expirationDate: expirationDate ? expirationDate.toString() : null
      };
    } else {
      patch = unchecked({ [field]: value ? value : null });
    }

    const update = await write(patch);
    if (update.error) {
      return ctx.error("internal", "Failed to update the quote", update.error);
    }
    return { ids };
  }
});
/**
 * Finalize a supplier quote.
 *
 * @remarks
 * Refused when the company requires a reachable supplier contact and the
 * supplier has none. Makes sure the quote has a share link, then
 * (`finalize-supplier-quote`, one transaction) checks every line is priced,
 * marks the quote Active and writes the supplier's price list.
 *
 * @mcp
 */
export const finalizeSupplierQuoteWithLink = defineServiceFn({
  input: z.object({ supplierQuoteId: z.string() }),
  permission: { create: "purchasing" },

  async run(ctx, { supplierQuoteId }) {
    const client = ctx.asSystem.supabase;
    const companyId = ctx.company.id;

    const owned = await refuseUnlessOwned(ctx, "supplierQuote", {
      id: supplierQuoteId
    });
    if (owned) return owned;

    const quote = await service.getSupplierQuote(client, supplierQuoteId);
    if (quote.error) {
      return ctx.error("internal", "Failed to get supplier quote", quote.error);
    }

    // A supplier with no reachable contact cannot be created as a vendor at
    // a connected platform, so its documents are rejected there long after
    // anyone is watching. No-op unless the company has turned it on.
    const contactRule = await checkPartyContactRequirement(client, companyId, {
      kind: "supplier",
      id: quote.data.supplierId
    });
    if (contactRule) return ctx.error("rule", contactRule);

    const link = await service.supplierQuoteLink(ctx, {
      ...quote.data,
      id: supplierQuoteId
    });
    if (link instanceof CarbonError) return link;

    const finalize = await invokePosting(
      ctx,
      "finalize-supplier-quote",
      { supplierQuoteId },
      service.finalizeSupplierQuote
    );
    if (finalize.error) {
      return fromServerFn(
        ctx,
        finalize.error,
        "Failed to finalize supplier quote"
      );
    }
    return { supplierQuoteId };
  }
});

/**
 * Send a supplier quote to the supplier.
 *
 * @remarks
 * Makes sure the quote has a share link and stamps it sent; the status stays
 * as it is. With `notification` Email, emails `supplierContact` (required
 * then) the link, copying `cc`, with the interaction's and the lines'
 * documents attached. Share sends nothing: the link is shared by hand.
 *
 * @mcp
 */
export const sendSupplierQuoteToSupplier = defineServiceFn({
  input: supplierQuoteFinalizeValidator.safeExtend({
    supplierQuoteId: z.string()
  }),
  permission: { create: "purchasing" },

  async run(ctx, { supplierQuoteId, notification, supplierContact, cc }) {
    const client = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;

    const owned = await refuseUnlessOwned(ctx, "supplierQuote", {
      id: supplierQuoteId
    });
    if (owned) return owned;

    const quote = await service.getSupplierQuote(client, supplierQuoteId);
    if (quote.error) {
      return ctx.error("internal", "Failed to get supplier quote", quote.error);
    }

    const link = await service.supplierQuoteLink(ctx, {
      ...quote.data,
      id: supplierQuoteId
    });
    if (link instanceof CarbonError) return link;

    const send = await service.sendSupplierQuote(
      client,
      supplierQuoteId,
      userId
    );
    if (send.error) {
      return ctx.error("internal", "Failed to send supplier quote", send.error);
    }

    if (notification !== "Email") return { supplierQuoteId };
    if (!supplierContact) {
      return ctx.error("validation", "Supplier contact is required for email");
    }

    const [company, contact, user, lines] = await Promise.all([
      getCompany(client, companyId),
      service.getSupplierContact(client, supplierContact, companyId),
      getUser(client, userId),
      service.getSupplierQuoteLines(client, supplierQuoteId)
    ]);
    if (!company.data || !contact.data?.contact || !user.data) {
      return ctx.error(
        "internal",
        "Failed to send email",
        company.error ?? contact.error ?? user.error
      );
    }

    const interactionId = quote.data.supplierInteractionId;
    const attachments = [
      ...(interactionId
        ? await service.interactionAttachments(
            client,
            companyId,
            interactionId,
            { withoutPurchaseOrderPdfs: true }
          )
        : []),
      ...(await service.getSupplierInteractionLineAttachments(
        client,
        companyId,
        (lines.data ?? []).flatMap((line) => (line.id ? [line.id] : []))
      ))
    ];

    const url = `${ERP_URL}${path.to.externalSupplierQuote(link)}`;
    const body = `Hey ${
      contact.data.contact.firstName || "there"
    },\n\nPlease provide pricing and lead time(s) for the linked quote:`;
    const signature = `Thanks,\n${user.data.firstName} ${user.data.lastName}\n${company.data.name}`;
    try {
      await trigger("send-email", {
        document: true,
        to: [user.data.email, contact.data.contact.email].filter(
          Boolean
        ) as string[],
        cc: cc?.length ? cc : undefined,
        from: user.data.email,
        subject: `Supplier Quote ${quote.data.supplierQuoteId} from ${company.data.name}`,
        html: `${body.replace(/\n/g, "<br>")}<br><a href="${url}">${url}</a><br><br>${signature.replace(/\n/g, "<br>")}`,
        text: `${body}\n\n${url}\n\n${signature}`,
        attachments,
        companyId
      });
    } catch (err) {
      return ctx.error("internal", "Failed to send email", err);
    }
    return { supplierQuoteId };
  }
});

// ── Supplier quote share link ────────────────────────────────────────────────
// The supplier answers through the quote's share link, which is the only
// credential: these run as the system, in the quote's company, on behalf of
// the quote's creator (`shareLinkContext`).
const supplierResponder = {
  submittedBy: z.string().min(1),
  submittedByEmail: z.string().email()
};

/**
 * Record that the supplier opened a quote's share link.
 *
 * @remarks
 * Stamps the link's `lastAccessedAt`.
 */
export const recordSupplierQuoteLinkVisit = defineServiceFn({
  input: z.object({ externalLinkId: z.string() }),
  permission: "system",

  async run(ctx, { externalLinkId }) {
    const visited = await ctx.asSystem.supabase
      .from("externalLink")
      .update({ lastAccessedAt: datetime.timestamp() } as never)
      .eq("id", externalLinkId)
      .eq("companyId", ctx.company.id);
    if (visited.error) {
      return ctx.error("internal", "Failed to record the visit", visited.error);
    }
    return { externalLinkId };
  }
});

/**
 * The supplier submits prices from a quote's share link.
 *
 * @remarks
 * Every line must be the quote's. Writes the price of each selected quantity
 * (the tax rate derived from the amounts), sets the quote Active with who
 * submitted it, stamps the link, and notifies the company's supplier-quote
 * group. A failed notification is logged; the submission stands.
 */
export const submitDigitalSupplierQuote = defineServiceFn({
  input: z.object({
    supplierQuoteId: z.string(),
    ...supplierResponder,
    selectedLines: z.record(
      z.string(),
      z.record(z.string(), selectedLineSchema)
    )
  }),
  permission: "system",

  async run(
    ctx,
    { supplierQuoteId, submittedBy, submittedByEmail, selectedLines }
  ) {
    const client = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const quote = await service.sharedSupplierQuote(ctx, supplierQuoteId);
    if (quote instanceof CarbonError) return quote;

    const prices = Object.entries(selectedLines).flatMap(
      ([lineId, byQuantity]) =>
        Object.entries(byQuantity).flatMap(([quantity, line]) =>
          Number(quantity) > 0 && line.quantity > 0
            ? [{ lineId, quantity: Number(quantity), line }]
            : []
        )
    );

    // The line ids come from the link's visitor and every write below runs as
    // the service role: each line must be this quote's.
    const lineIds = [...new Set(prices.map(({ lineId }) => lineId))];
    if (lineIds.length > 0) {
      const owned = await client
        .from("supplierQuoteLine")
        .select("id")
        .eq("supplierQuoteId", supplierQuoteId)
        .eq("companyId", companyId)
        .in("id", lineIds);
      if (owned.error) {
        return ctx.error(
          "internal",
          "Failed to read the quote lines",
          owned.error
        );
      }
      if (owned.data.length !== lineIds.length) {
        return ctx.error("validation", "Invalid selected lines data");
      }
    }

    const existing =
      lineIds.length > 0
        ? await client
            .from("supplierQuoteLinePrice")
            .select("supplierQuoteLineId, quantity")
            .eq("supplierQuoteId", supplierQuoteId)
            .in("supplierQuoteLineId", lineIds)
        : { data: [], error: null };
    if (existing.error) {
      return ctx.error(
        "internal",
        "Failed to save quote prices",
        existing.error
      );
    }
    const stored = new Set(
      existing.data.map((row) => `${row.supplierQuoteLineId}:${row.quantity}`)
    );

    const now = datetime.timestamp();
    const userId = quote.createdBy;
    const writes = prices.map(({ lineId, quantity, line }) => {
      const fields = {
        supplierUnitPrice: line.supplierUnitPrice ?? 0,
        leadTime: line.leadTime ?? 0,
        supplierShippingCost: line.supplierShippingCost ?? 0,
        supplierTaxAmount: line.supplierTaxAmount ?? 0,
        // The share page collects amounts only: the rate is derived from the
        // canonical denominator (unit price × quantity + shipping).
        taxPercent: deriveRate(
          line.supplierTaxAmount ?? 0,
          taxableBase(
            line.supplierUnitPrice ?? 0,
            quantity,
            line.supplierShippingCost ?? 0
          )
        )
      };
      return stored.has(`${lineId}:${quantity}`)
        ? client
            .from("supplierQuoteLinePrice")
            .update({ ...fields, updatedAt: now, updatedBy: userId })
            .eq("supplierQuoteId", supplierQuoteId)
            .eq("supplierQuoteLineId", lineId)
            .eq("quantity", quantity)
        : client.from("supplierQuoteLinePrice").insert({
            ...fields,
            supplierQuoteId,
            supplierQuoteLineId: lineId,
            companyId,
            quantity,
            exchangeRate: quote.exchangeRate ?? 1,
            createdBy: userId
          });
    });
    // ponytail: one write per price, as the page always did; batch if quotes grow large.
    const failed = (await Promise.all(writes)).find((write) => write.error);
    if (failed?.error) {
      return ctx.error("internal", "Failed to save quote prices", failed.error);
    }

    const submitted = await client
      .from("supplierQuote")
      .update({
        status: "Active",
        updatedAt: now,
        externalNotes: {
          ...((quote.externalNotes as Record<string, unknown>) || {}),
          lastSubmittedBy: submittedBy,
          lastSubmittedByEmail: submittedByEmail,
          lastSubmittedAt: now
        }
      })
      .eq("id", supplierQuoteId)
      .eq("companyId", companyId);
    if (submitted.error) {
      return ctx.error(
        "internal",
        "Failed to submit the quote",
        submitted.error
      );
    }

    if (quote.externalLinkId) {
      await client
        .from("externalLink")
        .update({ submittedAt: now, submittedBy, submittedByEmail } as never)
        .eq("id", quote.externalLinkId)
        .eq("companyId", companyId);
    }

    const settings = await getCompanySettings(client, companyId);
    if (settings.error) {
      logger.error("Failed to get company settings", { error: settings.error });
    }
    const groupIds = settings.data?.supplierQuoteNotificationGroup ?? [];
    if (groupIds.length > 0) {
      try {
        await trigger("notify", {
          companyId,
          documentId: supplierQuoteId,
          event: NotificationEvent.SupplierQuoteResponse,
          recipient: { type: "group", groupIds }
        });
      } catch (err) {
        logger.error("Failed to trigger supplier quote notification", {
          error: err
        });
      }
    }

    return { supplierQuoteId };
  }
});

/**
 * The supplier declines a quote from its share link.
 *
 * @remarks
 * Sets the quote Declined with who declined it and their note, and stamps the
 * link.
 */
export const declineDigitalSupplierQuote = defineServiceFn({
  input: z.object({
    supplierQuoteId: z.string(),
    ...supplierResponder,
    note: z.string().optional()
  }),
  permission: "system",

  async run(ctx, { supplierQuoteId, submittedBy, submittedByEmail, note }) {
    const client = ctx.asSystem.supabase;
    const quote = await service.sharedSupplierQuote(ctx, supplierQuoteId);
    if (quote instanceof CarbonError) return quote;

    const now = datetime.timestamp();
    const declined = await client
      .from("supplierQuote")
      .update({
        status: "Declined",
        updatedAt: now,
        externalNotes: {
          ...((quote.externalNotes as Record<string, unknown>) || {}),
          declineNote: note ?? null,
          declinedBy: submittedBy,
          declinedByEmail: submittedByEmail,
          declinedAt: now
        }
      })
      .eq("id", supplierQuoteId)
      .eq("companyId", ctx.company.id);
    if (declined.error) {
      return ctx.error(
        "internal",
        "Failed to decline the quote",
        declined.error
      );
    }

    if (quote.externalLinkId) {
      await client
        .from("externalLink")
        .update({
          declinedAt: now,
          declinedBy: submittedBy,
          declinedByEmail: submittedByEmail,
          declineNote: note ?? null
        } as never)
        .eq("id", quote.externalLinkId)
        .eq("companyId", ctx.company.id);
    }
    return { supplierQuoteId };
  }
});

/**
 * The supplier writes notes on a quote line from the quote's share link.
 *
 * @remarks
 * `notes` is a TipTap document, or null to clear them. The line must be the
 * quote's.
 */
export const updateDigitalSupplierQuoteLineNotes = defineServiceFn({
  input: z.object({
    supplierQuoteId: z.string(),
    lineId: z.string(),
    notes: z.unknown()
  }),
  permission: "system",

  async run(ctx, { supplierQuoteId, lineId, notes }) {
    const updated = await ctx.asSystem.supabase
      .from("supplierQuoteLine")
      .update({
        externalNotes: (notes ?? null) as Json,
        updatedAt: datetime.timestamp()
      })
      .eq("id", lineId)
      .eq("supplierQuoteId", supplierQuoteId)
      .eq("companyId", ctx.company.id);
    if (updated.error) {
      return ctx.error("internal", "Failed to update notes", updated.error);
    }
    return { lineId };
  }
});

// ── Suppliers ───────────────────────────────────────────────────────────────

/**
 * Submit a supplier for approval.
 *
 * @remarks
 * Opens an approval request under the company's supplier approval rule, sets
 * the supplier Pending, and notifies the rule's approvers. Refused when
 * suppliers need no approval, or a request is already pending.
 *
 * @mcp
 */
export const requestSupplierApproval = defineServiceFn({
  input: z.object({ supplierId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { supplierId }) {
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;
    const owned = await refuseUnlessOwned(ctx, "supplier", { id: supplierId });
    if (owned) return owned;

    const opened = await openApprovalRequests(ctx.asSystem.supabase, {
      documentType: "supplier",
      documentIds: [supplierId],
      companyId,
      userId
    });
    if (opened.status === "not-required") {
      return ctx.error("rule", "Suppliers do not require approval");
    }
    if (opened.status !== "opened") {
      return ctx.error("internal", "Failed to submit for approval");
    }
    if (opened.requested.length === 0) {
      return ctx.error(
        "conflict",
        "An approval request already exists for this supplier"
      );
    }

    const update = await ctx.asCaller.supabase
      .from("supplier")
      .update({
        supplierStatus: "Pending",
        updatedBy: userId,
        updatedAt: datetime.timestamp()
      })
      .eq("id", supplierId)
      .eq("companyId", companyId);
    if (update.error) {
      return ctx.error(
        "internal",
        "The approval request is open, but the supplier could not be set Pending",
        update.error
      );
    }

    if (opened.approverIds.length > 0) {
      await trigger("notify", {
        event: NotificationEvent.ApprovalRequested,
        companyId,
        documentId: supplierId,
        documentType: "supplier",
        recipient: { type: "users", userIds: opened.approverIds },
        from: userId
      }).catch((e) =>
        logger.error("Failed to trigger approval notification", { error: e })
      );
    }
    return { supplierId };
  }
});

/**
 * Deactivate a supplier.
 *
 * @remarks
 * Sets the supplier Inactive. Only someone who may approve suppliers may do
 * it.
 *
 * @mcp destructive
 */
export const deactivateSupplier = defineServiceFn({
  input: z.object({ supplierId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { supplierId }) {
    const companyId = ctx.company.id;
    const owned = await refuseUnlessOwned(ctx, "supplier", { id: supplierId });
    if (owned) return owned;

    const canApprove = await canApproveRequest(
      ctx.asSystem.supabase,
      { amount: null, documentType: "supplier", companyId },
      ctx.auditUserId
    );
    if (!canApprove) {
      return ctx.error(
        "forbidden",
        "You do not have permission to deactivate this supplier"
      );
    }

    const update = await ctx.asCaller.supabase
      .from("supplier")
      .update({
        supplierStatus: "Inactive",
        updatedBy: ctx.auditUserId,
        updatedAt: datetime.timestamp()
      })
      .eq("id", supplierId)
      .eq("companyId", companyId);
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to deactivate the supplier",
        update.error
      );
    }
    return { supplierId };
  }
});

/**
 * Approve or reject a supplier's pending approval request.
 *
 * @remarks
 * Only an approver under the supplier rule may decide. Approving sets the
 * supplier Active; rejecting sets it Rejected. The requester is notified when
 * someone else decided.
 *
 * @mcp
 */
export const decideSupplierApproval = defineServiceFn({
  input: approvalDecisionValidator.extend({ supplierId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { supplierId, approvalRequestId, decision, notes }) {
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;
    const owned = await refuseUnlessOwned(ctx, "supplier", { id: supplierId });
    if (owned) return owned;

    const result = await decideApprovalRequest(
      ctx.asSystem.supabase,
      ctx.asSystem.pg,
      {
        documentType: "supplier",
        documentId: supplierId,
        companyId,
        userId,
        approvalRequestId,
        decision,
        notes
      }
    );
    if (result.error) {
      return ctx.error(
        result.error.code === "not-found"
          ? "notFound"
          : result.error.code === "forbidden"
            ? "forbidden"
            : "internal",
        result.error.message
      );
    }

    if (result.requestedBy !== userId) {
      await trigger("notify", {
        event:
          decision === "Approved"
            ? NotificationEvent.ApprovalApproved
            : NotificationEvent.ApprovalRejected,
        companyId,
        documentId: supplierId,
        documentType: "supplier",
        recipient: { type: "user", userId: result.requestedBy },
        from: userId
      }).catch((e) =>
        logger.error("Failed to trigger approval decision notification", {
          error: e
        })
      );
    }
    return { supplierId, decision };
  }
});
// ── Purchase return orders ──────────────────────────────────────────────────

const returnOrderTextFields = [
  "purchaseOrderId",
  "supplierContactId",
  "supplierLocationId",
  "supplierReference",
  "expirationDate",
  "locationId",
  "orderDate"
] as const;

/**
 * Change one field of purchase return orders.
 *
 * @remarks
 * The return order properties panel's edit; `value` null clears the field. A
 * new `supplierId` on one return takes the supplier's currency and today's
 * rate. A new `currencyCode` takes today's rate (refused when there is
 * none). Refused when any of the returns is Completed or Cancelled.
 *
 * @mcp
 */
export const updateReturnOrders = defineServiceFn({
  input: z.object({
    ids: z.array(z.string()).min(1),
    field: z.enum(["supplierId", "currencyCode", ...returnOrderTextFields]),
    value: z.string().nullable()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { ids, field, value }) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;
    const statuses = await service.statusesOf(ctx, "purchaseReturnOrder", ids);
    if (statuses instanceof CarbonError) return statuses;
    if (statuses.some(isPurchaseReturnOrderLocked)) {
      return ctx.error(
        "rule",
        "Cannot modify a completed or cancelled return order."
      );
    }

    let patch: Database["public"]["Tables"]["purchaseReturnOrder"]["Update"];
    if (field === "supplierId") {
      patch = { supplierId: value ?? undefined };
      if (value && ids.length === 1) {
        const supplier = await client
          .from("supplier")
          .select("currencyCode")
          .eq("id", value)
          .single();
        const currencyCode = supplier.data?.currencyCode;
        if (currencyCode) {
          const rate = await getExchangeRate(client, companyId, currencyCode);
          if (rate.error)
            return ctx.error("rule", rate.error.message, rate.error);
          patch = { ...patch, currencyCode, exchangeRate: rate.data };
        }
      }
    } else if (field === "currencyCode" && value) {
      // Missing rate = refusal, never a stale rate or 1.
      const rate = await getExchangeRate(client, companyId, value);
      if (rate.error) return ctx.error("rule", rate.error.message, rate.error);
      patch = { currencyCode: value, exchangeRate: rate.data };
    } else {
      patch = unchecked({ [field]: value ? value : null });
    }

    const update = await client
      .from("purchaseReturnOrder")
      .update({
        ...patch,
        updatedBy: ctx.auditUserId,
        updatedAt: datetime.timestamp()
      })
      .in("id", ids)
      .eq("companyId", companyId);
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update the return order",
        update.error
      );
    }
    return { ids };
  }
});

/**
 * Cancel a purchase return order.
 *
 * @remarks
 * Refused when the return is Completed or Cancelled, or has a shipment or
 * shipped quantity. Locks the return first, so a shipment posting at the
 * same time either wins or sees it Cancelled.
 *
 * @mcp destructive
 */
export const cancelReturnOrder = defineServiceFn({
  input: z.object({ purchaseReturnOrderId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { purchaseReturnOrderId }) {
    try {
      await service.cancelPurchaseReturnOrder(ctx.asSystem.pg, {
        id: purchaseReturnOrderId,
        companyId: ctx.company.id,
        userId: ctx.auditUserId
      });
    } catch (err) {
      return service.refusedBy(ctx, err, "Failed to update status");
    }
    return { purchaseReturnOrderId };
  }
});

/**
 * Reopen a purchase return order.
 *
 * @remarks
 * Sets a To Ship or Cancelled return back to Draft, so its lines can be
 * edited and it can be confirmed again. Refused when anything has shipped.
 *
 * @mcp
 */
export const reopenReturnOrder = defineServiceFn({
  input: z.object({ purchaseReturnOrderId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { purchaseReturnOrderId }) {
    try {
      await service.reopenPurchaseReturnOrder(ctx.asSystem.pg, {
        id: purchaseReturnOrderId,
        companyId: ctx.company.id,
        userId: ctx.auditUserId
      });
    } catch (err) {
      return service.refusedBy(ctx, err, "Failed to update status");
    }
    return { purchaseReturnOrderId };
  }
});

const returnOrderLineInput = purchaseReturnOrderLineValidator
  .omit({ id: true, purchaseReturnOrderId: true })
  .extend({
    purchaseReturnOrderId: z.string(),
    customFields: customFieldsInput.optional()
  });

/**
 * Add a line to a purchase return order.
 *
 * @remarks
 * Only while the return is Draft: quantities are checked against their
 * source lines at Confirm. A line added from a purchase order or receipt
 * line links the return to that purchase order when it has none yet (best
 * effort). The batch or serial to send back is `trackedEntityIds`; with none
 * given and a receipt line holding exactly one Available entity, that one is
 * chosen.
 *
 * @mcp
 */
export const addReturnOrderLine = defineServiceFn({
  input: returnOrderLineInput,
  permission: { create: "purchasing" },

  async run(ctx, { trackedEntityIds, ...line }) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;
    const orderId = line.purchaseReturnOrderId;

    const order = await service.getPurchaseReturnOrder(client, orderId);
    if (isPurchaseReturnOrderLocked(order.data?.status)) {
      return ctx.error(
        "rule",
        "Cannot add lines to a completed or cancelled return order."
      );
    }
    if (order.data?.status !== "Draft") {
      return ctx.error(
        "rule",
        "Lines can only be added while the return order is Draft"
      );
    }

    const created = await service.upsertPurchaseReturnOrderLine(client, {
      ...line,
      companyId,
      createdBy: userId
    });
    if (created.error || !created.data) {
      return ctx.error(
        "internal",
        "Failed to create return order line",
        created.error
      );
    }
    const id = created.data.id;

    // The first line's order wins and a manually linked header is never
    // overwritten, so a return across several orders still works.
    if (!order.data.purchaseOrderId) {
      let purchaseOrderLineId = line.purchaseOrderLineId ?? null;
      if (!purchaseOrderLineId && line.receiptLineId) {
        const receiptLine = await client
          .from("receiptLine")
          .select("lineId")
          .eq("id", line.receiptLineId)
          .eq("companyId", companyId)
          .maybeSingle();
        purchaseOrderLineId = receiptLine.data?.lineId ?? null;
      }
      if (purchaseOrderLineId) {
        const purchaseOrderLine = await client
          .from("purchaseOrderLine")
          .select("purchaseOrderId")
          .eq("id", purchaseOrderLineId)
          .eq("companyId", companyId)
          .maybeSingle();
        if (purchaseOrderLine.data?.purchaseOrderId) {
          await client
            .from("purchaseReturnOrder")
            .update({
              purchaseOrderId: purchaseOrderLine.data.purchaseOrderId,
              updatedBy: userId
            })
            .eq("id", orderId)
            .eq("companyId", companyId);
        }
      }
    }

    let entityIds = trackedEntityIds ?? [];
    if (entityIds.length === 0 && line.receiptLineId) {
      const returnable = await service.getReturnableEntitiesForReceiptLine(
        client,
        companyId,
        line.itemId,
        line.receiptLineId
      );
      if (!returnable.error && returnable.data?.length === 1) {
        entityIds = [returnable.data[0].id];
      }
    }
    if (entityIds.length > 0) {
      const set = await service.setPurchaseReturnOrderLineTrackedEntities(
        client,
        id,
        companyId,
        entityIds,
        userId
      );
      if (set.error) {
        return ctx.error(
          "internal",
          "The line was added, but its tracked entities could not be set",
          set.error
        );
      }
    }
    return { id };
  }
});

/**
 * Change a line of a purchase return order.
 *
 * @remarks
 * Refused when the return is Completed or Cancelled, or the line is not on
 * it. Once the return is confirmed, the quantity, item, unit price,
 * restocking fee, unit of measure and source links are locked: they were
 * checked against their source lines at Confirm. `trackedEntityIds`
 * replaces the line's batches and serials.
 *
 * @mcp
 */
export const updateReturnOrderLine = defineServiceFn({
  input: returnOrderLineInput.extend({ lineId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { lineId, trackedEntityIds, ...line }) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;
    const orderId = line.purchaseReturnOrderId;

    const order = await service.getPurchaseReturnOrder(client, orderId);
    if (isPurchaseReturnOrderLocked(order.data?.status)) {
      return ctx.error(
        "rule",
        "Cannot modify a completed or cancelled return order."
      );
    }

    const existing = await client
      .from("purchaseReturnOrderLine")
      .select(
        "purchaseReturnOrderId, quantity, itemId, unitPrice, restockFeePercent, unitOfMeasureCode, purchaseOrderLineId, receiptLineId, purchaseInvoiceLineId"
      )
      .eq("id", lineId)
      .eq("companyId", companyId)
      .single();
    if (existing.error || existing.data.purchaseReturnOrderId !== orderId) {
      return ctx.error(
        "notFound",
        "This line does not belong to this return order"
      );
    }

    if (order.data?.status !== "Draft") {
      const locked = lockedReturnLineField(line, existing.data);
      if (locked) {
        return ctx.error("rule", `${locked} is locked after confirmation`);
      }
    }

    const update = await service.upsertPurchaseReturnOrderLine(client, {
      ...line,
      id: lineId,
      updatedBy: ctx.auditUserId
    });
    if (update.error) {
      return ctx.error(
        "internal",
        "Failed to update return order line",
        update.error
      );
    }

    const set = await service.setPurchaseReturnOrderLineTrackedEntities(
      client,
      lineId,
      companyId,
      trackedEntityIds ?? [],
      ctx.auditUserId
    );
    if (set.error) {
      return ctx.error("internal", "Failed to set tracked entities", set.error);
    }
    return { id: lineId };
  }
});

// ── Leases (lessee) ─────────────────────────────────────────────────────────
/**
 * Activate a Draft lease.
 *
 * @remarks
 * Classifies and measures each leased asset, posts the commencement journal
 * (or the opening balance, for a lease that commenced before the accounting
 * cutover) and writes the monthly schedule, in one transaction. Refused for a
 * lease that is not Draft, has no asset, an asset with no payment row, a
 * currency other than the base currency, or a Skipped payment no opening
 * balance holds.
 *
 * @mcp
 */
export const activateLease = defineServiceFn({
  input: z.object({ leaseId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { leaseId }) {
    const refused = await service.postLease(
      ctx,
      { type: "activate", leaseId },
      "Failed to activate lease"
    );
    return refused ?? { leaseId };
  }
});

/**
 * Cancel an Active lease.
 *
 * @remarks
 * Undoes an activation: voids its commencement or opening journal and deletes
 * the schedule. Refused for a Draft (delete it instead), and for a lease with
 * a Modify, Terminate or Purchase, an invoiced payment, or a posted or held
 * lease run month.
 *
 * @mcp destructive
 */
export const cancelLease = defineServiceFn({
  input: z.object({ leaseId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { leaseId }) {
    const refused = await service.postLease(
      ctx,
      { type: "cancel", leaseId },
      "Failed to cancel lease"
    );
    return refused ?? { leaseId };
  }
});

/**
 * Modify an Active lease from an effective date.
 *
 * @remarks
 * Updates the term, rate, frequency and escalation, cuts each active asset's
 * remaining payments again at the payment in `lines`, remeasures each
 * capitalized asset, posts the adjustment and rewrites the unposted schedule,
 * in one transaction. The effective date must start a lease month and a
 * payment period, after every posted lease run month.
 *
 * @mcp
 */
export const modifyLease = defineServiceFn({
  input: leaseModifyValidator.safeExtend({ leaseId: z.string() }),
  permission: { update: "purchasing" },

  async run(ctx, { leaseId, notes, ...terms }) {
    const refused = await service.postLease(
      ctx,
      { type: "modify", leaseId, ...terms, notes: notes ?? null },
      "Failed to modify lease"
    );
    return refused ?? { leaseId };
  }
});

/**
 * Terminate one leased asset early.
 *
 * @remarks
 * Deletes its Pending payments after the date, adds a Termination Penalty
 * payment of `penaltyAmount`, posts the derecognition with its gain or loss,
 * and sets the asset Terminated; the lease ends with its last asset. The
 * date must end a payment period, on or after the commencement.
 *
 * @mcp destructive
 */
export const terminateLeaseLine = defineServiceFn({
  input: leaseTerminateValidator.extend({
    leaseId: z.string(),
    leaseLineId: z.string()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { leaseId, leaseLineId, notes, ...terms }) {
    const refused = await service.postLease(
      ctx,
      {
        type: "terminate",
        leaseId,
        leaseLineId,
        ...terms,
        notes: notes ?? null
      },
      "Failed to terminate lease"
    );
    return refused ?? { leaseId, leaseLineId };
  }
});

/**
 * Exercise a leased asset's purchase option.
 *
 * @remarks
 * Posts the purchase, adds an Active fixed asset of `fixedAssetClassId` at
 * the asset's location, and sets the leased asset Purchased. Refused for a
 * Short-Term asset, and one with neither a purchase option nor ownership
 * transfer.
 *
 * @mcp
 */
export const purchaseLeaseLine = defineServiceFn({
  input: leasePurchaseValidator.extend({
    leaseId: z.string(),
    leaseLineId: z.string()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { leaseId, leaseLineId, notes, ...terms }) {
    const refused = await service.postLease(
      ctx,
      {
        type: "purchase",
        leaseId,
        leaseLineId,
        ...terms,
        notes: notes ?? null
      },
      "Failed to purchase the leased asset"
    );
    return refused ?? { leaseId, leaseLineId };
  }
});
/**
 * Override a Draft lease asset's classification.
 *
 * @remarks
 * Sets the asset Operating or Finance whatever the five tests say, with the
 * reason; activation keeps it. Only while the lease is Draft. Audit logged.
 *
 * @mcp
 */
export const overrideLeaseLineClassification = defineServiceFn({
  input: leaseClassificationValidator.extend({
    leaseId: z.string(),
    leaseLineId: z.string()
  }),
  permission: { update: "accounting" },

  async run(ctx, { leaseId, leaseLineId, classification, reason }) {
    const refused = await service.writeClassificationOverride(ctx, {
      leaseId,
      leaseLineId,
      override: { classification, reason }
    });
    return refused ?? { leaseLineId, classification };
  }
});

/**
 * Remove a Draft lease asset's classification override.
 *
 * @remarks
 * The five tests decide the classification again. Only while the lease is
 * Draft. Audit logged.
 *
 * @mcp
 */
export const removeLeaseLineClassificationOverride = defineServiceFn({
  input: z.object({ leaseId: z.string(), leaseLineId: z.string() }),
  permission: { update: "accounting" },

  async run(ctx, { leaseId, leaseLineId }) {
    const refused = await service.writeClassificationOverride(ctx, {
      leaseId,
      leaseLineId,
      override: null
    });
    return refused ?? { leaseLineId };
  }
});

// ── Purchase orders ─────────────────────────────────────────────────────────

const purchaseOrderHeaderFields = [
  "supplierContactId",
  "supplierLocationId",
  "supplierReference",
  "exchangeRate",
  "orderDate"
] as const;

const purchaseOrderDeliveryFields = [
  "receiptRequestedDate",
  "locationId",
  "deliveryDate"
] as const;

/**
 * Change one field of purchase orders.
 *
 * @remarks
 * The purchase order properties panel's edit; `value` null clears the field
 * (an empty `supplierId` changes nothing). A new `supplierId` on one order
 * takes the supplier's currency and today's rate; a new `currencyCode` takes
 * today's rate (refused when there is none). `receiptRequestedDate`,
 * `receiptPromisedDate`, `locationId` and `deliveryDate` are the delivery's;
 * a new date also moves the lines still on the order's previous one. Refused
 * when any order is released, except for `deliveryDate`, and for
 * `receiptPromisedDate` until the order is fully received (To Invoice,
 * Completed or Closed).
 *
 * @mcp
 */
export const updatePurchaseOrders = defineServiceFn({
  input: z.object({
    ids: z.array(z.string()).min(1),
    field: z.enum([
      "supplierId",
      "currencyCode",
      "receiptPromisedDate",
      ...purchaseOrderHeaderFields,
      ...purchaseOrderDeliveryFields
    ]),
    value: z.string().nullable()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { ids, field, value }) {
    const client = ctx.asCaller.supabase;
    const companyId = ctx.company.id;
    const stamp = () => ({
      updatedBy: ctx.auditUserId,
      updatedAt: datetime.timestamp()
    });

    if (field === "receiptPromisedDate") {
      const statuses = await service.statusesOf(ctx, "purchaseOrder", ids);
      if (statuses instanceof CarbonError) return statuses;
      const refusal = statuses
        .map(purchaseOrderPromisedDateRefusal)
        .find((message) => message !== null);
      if (refusal) return ctx.error("rule", refusal);
    } else if (field !== "deliveryDate") {
      const statuses = await service.statusesOf(ctx, "purchaseOrder", ids);
      if (statuses instanceof CarbonError) return statuses;
      if (statuses.some(isPurchaseOrderLocked)) {
        return ctx.error("rule", "Cannot modify a confirmed purchase order.");
      }
    }

    const failed = (error: unknown) =>
      ctx.error("internal", "Failed to update the purchase order", error);

    if (isPurchaseOrderDateField(field)) {
      // One transaction: the lines compare against the order's previous date,
      // so they are written before the delivery row changes it.
      const saved = await ctx
        .transaction(async (tx) => {
          const db = tx.asSystem.pg;
          await service.cascadePurchaseOrderDateToLines(db, {
            companyId,
            userId: ctx.auditUserId,
            purchaseOrderIds: ids,
            field,
            value
          });
          await db
            .updateTable("purchaseOrderDelivery")
            .set({ [field]: value, ...stamp() })
            .where("id", "in", ids)
            .where("companyId", "=", companyId)
            .execute();
        })
        .catch(failed);
      return saved instanceof CarbonError ? saved : { ids };
    }

    if ((purchaseOrderDeliveryFields as readonly string[]).includes(field)) {
      const delivery = await client
        .from("purchaseOrderDelivery")
        .update(unchecked({ [field]: value, ...stamp() }))
        .in("id", ids)
        .eq("companyId", companyId);
      return delivery.error ? failed(delivery.error) : { ids };
    }

    let patch: Database["public"]["Tables"]["purchaseOrder"]["Update"];
    if (field === "supplierId") {
      patch = { supplierId: value ?? undefined };
      if (value && ids.length === 1) {
        const supplier = await client
          .from("supplier")
          .select("currencyCode")
          .eq("id", value)
          .single();
        const currencyCode = supplier.data?.currencyCode;
        if (currencyCode) {
          const rate = await getExchangeRate(client, companyId, currencyCode);
          if (rate.error)
            return ctx.error("rule", rate.error.message, rate.error);
          patch = { ...patch, currencyCode, exchangeRate: rate.data };
        }
      }
    } else if (field === "currencyCode" && value) {
      const rate = await getExchangeRate(client, companyId, value);
      if (rate.error) return ctx.error("rule", rate.error.message, rate.error);
      patch = { currencyCode: value, exchangeRate: rate.data };
    } else {
      patch = unchecked({ [field]: value ? value : null });
    }

    const update = await client
      .from("purchaseOrder")
      .update({ ...patch, ...stamp() })
      .in("id", ids)
      .eq("companyId", companyId);
    return update.error ? failed(update.error) : { ids };
  }
});

/**
 * Change one date of a purchase order line.
 *
 * @remarks
 * The requested date is refused once the order is released, the promised date
 * once the line or the order is received; the delivery date can always be
 * corrected.
 *
 * @param lineId - The purchase order line's id.
 * @param field - Which date: `requiredDate`, `promisedDate` or `receivedDate`.
 * @param value - The date, `YYYY-MM-DD`, or null to clear it.
 * @mcp
 */
export const updatePurchaseOrderLineDate = defineServiceFn({
  input: z.object({
    lineId: z.string().min(1),
    field: z.enum(purchaseOrderLineDateFields),
    value: z.string().refine(isIsoDate, "Use a YYYY-MM-DD date").nullable()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { lineId, field, value }) {
    const companyId = ctx.company.id;
    const db = ctx.asSystem.pg;
    const failed = (error: unknown) =>
      ctx.error("internal", "Failed to update the purchase order line", error);

    const line = await db
      .selectFrom("purchaseOrderLine")
      .innerJoin("purchaseOrder", (join) =>
        join
          .onRef("purchaseOrder.id", "=", "purchaseOrderLine.purchaseOrderId")
          .onRef("purchaseOrder.companyId", "=", "purchaseOrderLine.companyId")
      )
      .select(["purchaseOrderLine.receivedComplete", "purchaseOrder.status"])
      .where("purchaseOrderLine.id", "=", lineId)
      .where("purchaseOrderLine.companyId", "=", companyId)
      .executeTakeFirst()
      .catch(failed);
    if (line instanceof CarbonError) return line;
    if (!line) return ctx.error("notFound", "Purchase order line not found");

    const refusal = purchaseOrderLineDateRefusal(field, line);
    if (refusal) return ctx.error("rule", refusal);

    const updated = await db
      .updateTable("purchaseOrderLine")
      .set({
        [field]: value,
        updatedBy: ctx.auditUserId,
        updatedAt: datetime.timestamp()
      })
      .where("id", "=", lineId)
      .where("companyId", "=", companyId)
      .execute()
      .catch(failed);
    return updated instanceof CarbonError ? updated : { lineId };
  }
});

/**
 * Save a purchase order's Shipping card. Refused once the order is released.
 * A new date also moves the lines still on the order's previous one.
 */
export const updatePurchaseOrderDelivery = defineServiceFn({
  input: z.object({
    id: z.string().min(1),
    locationId: z.string().optional(),
    shippingMethodId: z.string().optional(),
    trackingNumber: z.string(),
    deliveryDate: z.string().optional(),
    receiptRequestedDate: z.string().optional(),
    receiptPromisedDate: z.string().optional(),
    dropShipment: z.boolean(),
    customerId: z.string().optional(),
    customerLocationId: z.string().optional(),
    supplierShippingCost: z.number().optional(),
    notes: z.string().optional(),
    incoterm: z.enum(incoterms).optional(),
    incotermLocation: z.string().optional(),
    customFields: z.record(z.string(), z.unknown()).optional()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { id, customFields, ...delivery }) {
    const companyId = ctx.company.id;
    const statuses = await service.statusesOf(ctx, "purchaseOrder", [id]);
    if (statuses instanceof CarbonError) return statuses;
    if (statuses.length === 0) {
      return ctx.error("notFound", "Purchase order not found");
    }
    if (statuses.some(isPurchaseOrderLocked)) {
      return ctx.error("rule", "Cannot modify a confirmed purchase order.");
    }

    const saved = await ctx
      .transaction(async (tx) => {
        const db = tx.asSystem.pg;
        for (const field of [
          "receiptRequestedDate",
          "receiptPromisedDate",
          "deliveryDate"
        ] as const) {
          await service.cascadePurchaseOrderDateToLines(db, {
            companyId,
            userId: ctx.auditUserId,
            purchaseOrderIds: [id],
            field,
            value: delivery[field] ?? null
          });
        }
        await db
          .updateTable("purchaseOrderDelivery")
          .set({
            ...sanitize(delivery),
            customFields: (customFields ?? null) as Json,
            updatedBy: ctx.auditUserId,
            updatedAt: datetime.timestamp()
          })
          .where("id", "=", id)
          .where("companyId", "=", companyId)
          .execute();
      })
      .catch((error: unknown) =>
        ctx.error("internal", "Failed to update purchase order delivery", error)
      );
    return saved instanceof CarbonError ? saved : { id };
  }
});

/**
 * Delete purchase orders.
 *
 * @remarks
 * Deletes the Draft and Planned orders, and the Needs Approval orders the
 * caller requested (their pending approval requests are cancelled first),
 * and skips the rest: an approver rejects an order instead of deleting it.
 * Refused, with the first order's reason, when none could be deleted.
 *
 * @returns `purchaseOrderIds`, the orders deleted, and `skipped`, how many were not.
 *
 * @mcp destructive
 */
export const deletePurchaseOrders = defineServiceFn({
  input: z.object({ purchaseOrderIds: z.array(z.string()).min(1) }),
  permission: { delete: "purchasing" },

  async run(ctx, { purchaseOrderIds }) {
    const system = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;
    const ids = [...new Set(purchaseOrderIds)];

    const orders = await fetchAllByIds(ids, (batch) =>
      system
        .from("purchaseOrder")
        .select("id, status")
        .in("id", batch)
        .eq("companyId", companyId)
        .order("id")
    );
    if (orders.error) {
      return ctx.error(
        "internal",
        "Failed to read the purchase orders",
        orders.error
      );
    }

    const inApproval = orders.data
      .filter((order) => order.status === "Needs Approval")
      .map((order) => order.id);
    const pending =
      inApproval.length > 0
        ? await fetchAllByIds(inApproval, (batch) =>
            system
              .from("approvalRequest")
              .select("id, documentId, requestedBy, amount, requestedAt")
              .eq("documentType", "purchaseOrder")
              .in("documentId", batch)
              .eq("companyId", companyId)
              .eq("status", "Pending")
              .order("requestedAt", { ascending: false })
              .order("id")
          )
        : null;
    if (pending?.error) {
      return ctx.error(
        "internal",
        "Failed to read the approval requests",
        pending.error
      );
    }

    const deletable: string[] = [];
    let refused: {
      status: string | null;
      refusal: "status" | "notRequester";
      amount: number | null;
    } | null = null;
    for (const order of orders.data) {
      const latest = pending?.data.find((r) => r.documentId === order.id);
      const refusal = purchaseOrderDeleteRefusal({
        status: order.status,
        requestedBy: latest?.requestedBy,
        userId
      });
      if (refusal) {
        refused ??= {
          status: order.status,
          refusal,
          amount: latest?.amount ?? null
        };
      } else {
        deletable.push(order.id);
      }
    }

    if (deletable.length === 0) {
      if (!refused) return ctx.error("notFound", "Purchase order not found");
      if (refused.refusal === "status") {
        return ctx.error(
          "rule",
          `Cannot delete purchase order with status "${refused.status ?? "unknown"}". Only Draft, Planned, or Needs Approval (if you're the requester) purchase orders can be deleted.`
        );
      }
      const isApprover = await canApproveRequest(
        system,
        {
          amount: refused.amount,
          documentType: "purchaseOrder",
          companyId
        },
        userId
      );
      return ctx.error(
        "forbidden",
        isApprover
          ? "Please reject the approval request instead of deleting"
          : "You do not have permission to delete this purchase order"
      );
    }

    // Each order is deleted only in the status it was checked in: one sent
    // for approval since it was read as a Draft stays, with its request.
    const deletableByStatus = groupBy(
      orders.data.filter((order) => deletable.includes(order.id)),
      (order) => order.status!
    );
    // One transaction: a delete that fails (an invoice line still names the
    // order) must leave its approval requests pending.
    const removed = await ctx
      .transaction(async (tx) => {
        const rows = await tx.asSystem.pg
          .deleteFrom("purchaseOrder")
          .where("companyId", "=", companyId)
          .where((eb) =>
            eb.or(
              Object.entries(deletableByStatus).map(([status, group]) =>
                eb.and([
                  eb(
                    "id",
                    "in",
                    group.map((order) => order.id)
                  ),
                  eb("status", "=", status as PurchaseOrderStatus)
                ])
              )
            )
          )
          .returning(["id", "status"])
          .execute();
        await service.cancelPendingApprovals(tx.asSystem.pg, {
          companyId,
          userId,
          purchaseOrderIds: rows
            .filter((row) => row.status === "Needs Approval")
            .map((row) => row.id)
        });
        return rows;
      })
      .catch((err) =>
        ctx.error("internal", "Failed to delete purchase orders", err)
      );
    if (removed instanceof CarbonError) return removed;
    const deleted = (removed.data ?? []).map((order) => order.id);
    return { purchaseOrderIds: deleted, skipped: ids.length - deleted.length };
  }
});

/** The PO statuses whose open lines MRP counts as supply
 *  (`openPurchaseOrderLines`). */
const MRP_SUPPLY_STATUSES = new Set<string>([
  "Planned",
  "To Receive",
  "To Receive and Invoice"
]);
/**
 * Reopen a purchase order.
 *
 * @remarks
 * Moves the order back to Draft (from the order page) or Planned (from the
 * planning pages: Draft is not MRP supply). Reopening a released order needs
 * `delete: purchasing`. Pending approval requests are cancelled; an order
 * that needs approval can be reopened only by its requester or an approver.
 * With `createRevision`, a released order is reopened as its next revision
 * (refused for an order never released). Reopening to Planned runs MRP for
 * the order unless it already was supply.
 *
 * @mcp
 */
export const reopenPurchaseOrder = defineServiceFn({
  input: z.object({
    purchaseOrderId: z.string(),
    status: z.enum(PURCHASE_ORDER_REOPEN_STATUSES),
    createRevision: z.boolean().default(false)
  }),
  permission: { update: "purchasing" },

  async run(ctx, { purchaseOrderId, status, createRevision }) {
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;

    const current = await ctx.asCaller.supabase
      .from("purchaseOrder")
      .select("status, orderDate")
      .eq("id", purchaseOrderId)
      .eq("companyId", companyId)
      .maybeSingle();
    if (current.error) {
      return ctx.error(
        "internal",
        "Failed to read the purchase order",
        current.error
      );
    }
    if (!current.data) return ctx.error("notFound", "Purchase order not found");
    const currentStatus = current.data.status;

    // Checked BEFORE the approvals are cancelled below: a request about to
    // fail must not have side effects. The revision write re-checks in SQL.
    if (
      createRevision &&
      !canCreatePurchaseOrderRevision({
        newStatus: status,
        currentStatus,
        orderDate: current.data.orderDate
      })
    ) {
      return ctx.error("rule", "Only a released purchase order can be revised");
    }
    if (
      isPurchaseOrderLocked(currentStatus) &&
      !ctx.can({ delete: "purchasing" })
    ) {
      return ctx.error(
        "forbidden",
        "Reopening a released purchase order needs permission to delete purchase orders"
      );
    }

    if (currentStatus === "Needs Approval") {
      const latest = await ctx.asSystem.supabase
        .from("approvalRequest")
        .select("requestedBy, amount")
        .eq("documentType", "purchaseOrder")
        .eq("documentId", purchaseOrderId)
        .eq("companyId", companyId)
        .eq("status", "Pending")
        .limit(1)
        .maybeSingle();
      if (latest.error) {
        return ctx.error(
          "internal",
          "Failed to read the approval requests",
          latest.error
        );
      }
      // Only the requester or an approver: anyone else would bypass the
      // approval by reopening.
      if (
        latest.data &&
        latest.data.requestedBy !== userId &&
        !(await canApproveRequest(
          ctx.asSystem.supabase,
          {
            amount: latest.data.amount,
            documentType: "purchaseOrder",
            companyId
          },
          userId
        ))
      ) {
        return ctx.error(
          "forbidden",
          "You do not have permission to reopen this purchase order"
        );
      }
    }
    // One transaction: a reopen that fails leaves the requests pending.
    const reopened = await ctx
      .transaction(async (tx) => {
        if (currentStatus === "Needs Approval" || currentStatus === "Closed") {
          await service.cancelPendingApprovals(tx.asSystem.pg, {
            companyId,
            userId,
            purchaseOrderIds: [purchaseOrderId]
          });
        }
        if (!createRevision) {
          await service.setPurchaseOrderStatus(tx.asSystem.pg, {
            id: purchaseOrderId,
            companyId,
            status,
            assignee: undefined,
            updatedBy: userId
          });
          return false;
        }
        const rows = await service.reopenPurchaseOrderAsRevision(
          tx.asSystem.pg,
          { id: purchaseOrderId, companyId, updatedBy: userId, status }
        );
        return rows === 0
          ? tx.error(
              "conflict",
              "Only a released purchase order can be revised"
            )
          : true;
      })
      .catch((err) =>
        ctx.error(
          "internal",
          createRevision
            ? "Failed to create revision"
            : "Failed to update purchasing order status",
          err
        )
      );
    if (reopened instanceof CarbonError) return reopened;
    if (reopened.error) return reopened.error;
    if (reopened.data) return { purchaseOrderId, status, revision: true };

    // Planned makes the lines MRP supply. An order that already was supply
    // changes nothing MRP reads, so the reopen does not wait on a run.
    if (status === "Planned" && !MRP_SUPPLY_STATUSES.has(currentStatus ?? "")) {
      await runMRP(ctx.asSystem.supabase, ctx.asSystem.pg, {
        type: "purchaseOrder",
        id: purchaseOrderId,
        companyId,
        userId
      });
    }
    return { purchaseOrderId, status, revision: false };
  }
});

/**
 * Close a purchase order.
 *
 * @remarks
 * Sets the order Closed and clears its assignee; nothing more is received or
 * invoiced against it. Its pending approval requests are cancelled. Needs
 * permission to update and to delete purchase orders.
 *
 * @mcp destructive
 */
export const closePurchaseOrderAndApprovals = defineServiceFn({
  input: z.object({ purchaseOrderId: z.string() }),
  // The status write runs as the system: update is what RLS demanded of it.
  permission: { update: "purchasing", delete: "purchasing" },

  async run(ctx, { purchaseOrderId }) {
    const owned = await refuseUnlessOwned(ctx, "purchaseOrder", {
      id: purchaseOrderId
    });
    if (owned) return owned;

    // One transaction: a close that fails leaves the requests pending.
    const closed = await ctx
      .transaction(async (tx) => {
        const requests = await service.cancelPendingApprovals(tx.asSystem.pg, {
          companyId: ctx.company.id,
          userId: ctx.auditUserId,
          purchaseOrderIds: [purchaseOrderId]
        });
        await service.setPurchaseOrderStatus(tx.asSystem.pg, {
          id: purchaseOrderId,
          companyId: ctx.company.id,
          status: "Closed",
          assignee: null,
          updatedBy: ctx.auditUserId
        });
        return requests.length;
      })
      .catch((err) =>
        ctx.error("internal", "Failed to update purchasing order status", err)
      );
    if (closed instanceof CarbonError) return closed;
    if (closed.data) {
      logger.info("Cancelled pending approval requests when closing", {
        companyId: ctx.company.id,
        purchaseOrderId,
        count: closed.data
      });
    }
    return { purchaseOrderId };
  }
});
const purchaseOrderNotification = {
  notification: z.enum(["Email", "None"]).optional(),
  supplierContact: z.string().optional(),
  cc: z.array(z.string()).optional(),
  /** The PDF's and email's locale (BCP 47); en-US when absent. */
  locale: z.string().optional()
};

/**
 * Finalize a purchase order.
 *
 * @remarks
 * Refused when the company requires a reachable supplier contact and the
 * supplier has none, or requires approved suppliers and this one is not
 * Active. The order gets its status from its lines and today's order date.
 * When the company's approval rule covers its total (a planning order skips
 * it if the company allows), it goes to Needs Approval instead: an approval
 * request is opened and the approvers notified, and nothing else happens
 * until it is approved. Otherwise the supplier prices are updated (when the
 * company does that on finalize), the PDF is stored as a document, and with
 * `notification` Email the supplier contact gets it with the interaction's
 * files and the default attachments (refused over the attachment limit).
 *
 * @mcp
 */
export const finalizePurchaseOrderAndNotify = defineServiceFn({
  input: z
    .object({ purchaseOrderId: z.string(), ...purchaseOrderNotification })
    .refine((d) => (d.notification === "Email" ? !!d.supplierContact : true), {
      message: "Supplier contact is required for email",
      path: ["supplierContact"]
    }),
  // Submitting for approval writes as the system: update is what RLS
  // demanded of that status write.
  permission: { create: "purchasing", update: "purchasing" },

  async run(
    ctx,
    { purchaseOrderId, notification, supplierContact, cc, locale }
  ) {
    const system = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;

    const purchaseOrder = await service.getPurchaseOrder(
      system,
      purchaseOrderId
    );
    if (purchaseOrder.error) {
      return ctx.error(
        "internal",
        "Failed to get purchase order",
        purchaseOrder.error
      );
    }
    if (purchaseOrder.data.companyId !== companyId) {
      return ctx.error("notFound", "Purchase order not found");
    }

    const contactRule = await checkPartyContactRequirement(
      ctx.asCaller.supabase,
      companyId,
      { kind: "supplier", id: purchaseOrder.data.supplierId }
    );
    if (contactRule) return ctx.error("rule", contactRule);

    if (
      purchaseOrder.data.supplierId &&
      (await isApprovalRequired(system, "supplier", companyId))
    ) {
      const supplier = await service.getSupplier(
        system,
        purchaseOrder.data.supplierId
      );
      if (supplier.data?.status !== "Active") {
        return ctx.error(
          "rule",
          "Cannot finalize: supplier is not approved (Active)"
        );
      }
    }

    // A planning order, untouched by hand since, skips the approval rule when
    // the company allows it. Fail closed: a failed read is an ordinary check.
    const [planningOrigin, planningSettings] = await Promise.all([
      system
        .from("purchaseOrder")
        .select("createdFromPlanning")
        .eq("id", purchaseOrderId)
        .eq("companyId", companyId)
        .maybeSingle(),
      system
        .from("companySettings")
        .select("skipApprovalForPlanningPurchaseOrders")
        .eq("id", companyId)
        .maybeSingle()
    ]);
    if (planningOrigin.error || planningSettings.error) {
      logger.error("Failed to read the planning approval bypass", {
        companyId,
        purchaseOrderId,
        error: planningOrigin.error ?? planningSettings.error
      });
    }
    const skipsApproval =
      planningOrigin.data?.createdFromPlanning === true &&
      planningSettings.data?.skipApprovalForPlanningPurchaseOrders === true;
    const amount = purchaseOrder.data.orderTotal ?? 0;
    const approvalRequired =
      !skipsApproval &&
      (await isApprovalRequired(system, "purchaseOrder", companyId, amount));

    // The PDF, the email and the prices wait for the approval. The order is
    // never released first: the status and the request are one transaction,
    // so it cannot be left released with no approval.
    if (approvalRequired) {
      const orderDate = datetime
        .today(await getCompanyTimeZone(system, companyId))
        .toString();
      const submitted = await ctx
        .transaction((tx) =>
          service.submitPurchaseOrderForApproval(tx.asSystem.pg, {
            id: purchaseOrderId,
            companyId,
            userId,
            amount,
            orderDate
          })
        )
        .catch((err) =>
          ctx.error(
            "internal",
            "Failed to submit the purchase order for approval",
            err
          )
        );
      if (submitted instanceof CarbonError) return submitted;
      trackWorkEvent(
        "purchase_order_finalized",
        { companyId, userId, purchaseOrderId, stage: "gated" },
        { discriminator: "gated" }
      );

      if (submitted.data) {
        const rule = await getApprovalRuleByAmount(
          system,
          "purchaseOrder",
          companyId,
          amount
        );
        const approverIds = rule.data
          ? await getApproverUserIdsForRule(system, rule.data)
          : [];
        if (approverIds.length > 0) {
          await trigger("notify", {
            event: NotificationEvent.ApprovalRequested,
            companyId,
            documentId: purchaseOrderId,
            documentType: "purchaseOrder",
            recipient: { type: "users", userIds: approverIds },
            from: userId
          }).catch((e) =>
            logger.error("Failed to trigger approval notification", {
              error: e
            })
          );
        }
      }
      return { purchaseOrderId, needsApproval: true };
    }

    const finalize = await service.finalizePurchaseOrder(
      ctx.asCaller.supabase,
      purchaseOrderId,
      userId
    );
    if (finalize.error) {
      return ctx.error(
        "internal",
        "Failed to finalize purchase order",
        finalize.error
      );
    }
    trackWorkEvent(
      "purchase_order_finalized",
      { companyId, userId, purchaseOrderId, stage: "committed" },
      { discriminator: "committed" }
    );

    await service.updatePricesOnFinalize(ctx, purchaseOrderId);

    const pdf = await service.attachPurchaseOrderPdf(ctx, {
      purchaseOrder: purchaseOrder.data,
      locale: locale ?? "en-US"
    });
    if (pdf instanceof CarbonError) return pdf;

    if (notification === "Email" && supplierContact) {
      try {
        const email = await service.purchaseOrderEmail(ctx, {
          purchaseOrderId,
          supplierContactId: supplierContact,
          locale: locale ?? "en-US"
        });
        if (email) {
          const interactionId = email.purchaseOrder.supplierInteractionId;
          const defaults = await service.getDefaultAttachmentsForPO(system, {
            companyId,
            supplierId: email.purchaseOrder.supplierId ?? null,
            itemIds: [
              ...new Set(
                email.lines.flatMap((line) =>
                  line.itemId ? [line.itemId] : []
                )
              )
            ]
          });
          const attachments = [
            ...(await service.signedAttachments(system, companyId, [
              { filename: pdf.fileName, path: pdf.path }
            ])),
            ...(interactionId
              ? await service.interactionAttachments(
                  system,
                  companyId,
                  interactionId,
                  { withoutPurchaseOrderPdfs: true }
                )
              : []),
            ...(await service.signedAttachments(
              system,
              companyId,
              defaults.map((file) => ({ filename: file.name, path: file.path }))
            ))
          ];
          const totalKb = attachments.length
            ? pdf.size + defaults.reduce((sum, r) => sum + (r.size ?? 0), 0)
            : 0;
          if (totalKb > PO_EMAIL_ATTACHMENT_LIMIT_MB * 1024) {
            return ctx.error(
              "rule",
              `Total attachments exceed ${PO_EMAIL_ATTACHMENT_LIMIT_MB} MB limit`
            );
          }
          await trigger("send-email", {
            document: true,
            to: email.to,
            cc: cc?.length ? cc : undefined,
            from: email.from,
            subject: email.subject,
            html: email.html,
            text: email.text,
            attachments: attachments.length ? attachments : undefined,
            companyId
          });
        }
      } catch (err) {
        return ctx.error("internal", "Failed to send email", err);
      }
    }
    return { purchaseOrderId, needsApproval: false };
  }
});

/**
 * Approve or reject a purchase order's pending approval request.
 *
 * @remarks
 * Only an approver whose tier covers the order's amount may decide. The
 * requester is notified, and so are the approvers of every lower tier. An
 * approved order is released: the supplier prices are updated (when the
 * company does that on finalize), the PDF is stored as a document, and with
 * `notification` Email the supplier contact gets it. Those follow-ups are
 * logged when they fail; the decision stands.
 *
 * @mcp
 */
export const decidePurchaseOrderApproval = defineServiceFn({
  input: z
    .object({
      purchaseOrderId: z.string(),
      approvalRequestId: z.string().min(1),
      decision: z.enum(["Approved", "Rejected"]),
      ...purchaseOrderNotification
    })
    .refine((d) => (d.notification === "Email" ? !!d.supplierContact : true), {
      message: "Supplier contact is required for email",
      path: ["supplierContact"]
    }),
  permission: { update: "purchasing" },

  async run(ctx, input) {
    const { purchaseOrderId, approvalRequestId, decision } = input;
    const system = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;

    const request = await getLatestApprovalRequestForDocument(
      system,
      "purchaseOrder",
      purchaseOrderId
    );
    // The request must be this order's pending one AND this company's.
    if (
      !request.data ||
      request.data.id !== approvalRequestId ||
      request.data.companyId !== companyId
    ) {
      return ctx.error("notFound", "Approval request not found");
    }
    const canApprove = await canApproveRequest(
      system,
      {
        amount: request.data.amount,
        documentType: request.data.documentType,
        companyId
      },
      userId
    );
    if (!canApprove) {
      return ctx.error(
        "forbidden",
        "You do not have permission to approve this request"
      );
    }

    const decided =
      decision === "Approved"
        ? await approveRequest(ctx.asSystem.pg, approvalRequestId, userId)
        : await rejectRequest(ctx.asSystem.pg, approvalRequestId, userId);
    if (decided.error && "code" in decided.error) {
      return ctx.error("validation", decided.error.message);
    }
    if (decided.error) {
      return ctx.error(
        "internal",
        decided.error.message ?? "Failed to process approval decision",
        decided.error
      );
    }

    const event =
      decision === "Approved"
        ? NotificationEvent.ApprovalApproved
        : NotificationEvent.ApprovalRejected;
    const requestedBy = request.data.requestedBy;
    if (requestedBy && requestedBy !== userId) {
      await trigger("notify", {
        event,
        companyId,
        documentId: purchaseOrderId,
        documentType: "purchaseOrder",
        recipient: { type: "user", userId: requestedBy },
        from: userId
      }).catch((e) =>
        logger.error("Failed to trigger approval decision notification", {
          error: e
        })
      );
    }
    // The approvers of every lower tier see spend that bypassed their tier.
    try {
      const lowerTier = await getLowerTierApproverUserIds(
        system,
        "purchaseOrder",
        companyId,
        request.data.amount ?? undefined
      );
      const recipients = lowerTier.filter(
        (id) => id !== requestedBy && id !== userId
      );
      if (recipients.length > 0) {
        await trigger("notify", {
          event,
          companyId,
          documentId: purchaseOrderId,
          documentType: "purchaseOrder",
          recipient: { type: "users", userIds: recipients },
          from: userId
        });
      }
    } catch (e) {
      logger.error(
        "Failed to trigger lower-tier spend notification for purchase order",
        { error: e }
      );
    }

    if (decision === "Approved") {
      await service.releaseApprovedPurchaseOrder(ctx, input);
    }
    return { purchaseOrderId, decision };
  }
});
/**
 * Confirm a purchase return order.
 *
 * @remarks
 * Moves a Draft return to To Ship after checking, under row locks, that no
 * line returns more than its source received, ordered or was invoiced. Then
 * stores the return's PDF as a document; when that fails the return stays
 * confirmed and `warning` says so.
 *
 * @mcp
 */
export const confirmReturnOrder = defineServiceFn({
  input: z.object({
    purchaseReturnOrderId: z.string(),
    /** The PDF's locale (BCP 47); en-US when absent. */
    locale: z.string().optional()
  }),
  permission: { update: "purchasing" },

  async run(ctx, { purchaseReturnOrderId, locale }) {
    const system = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const userId = ctx.auditUserId;

    const order = await service.getPurchaseReturnOrder(
      system,
      purchaseReturnOrderId
    );
    if (order.error) {
      return ctx.error(
        "internal",
        "Failed to load purchase return order",
        order.error
      );
    }
    if (order.data.companyId !== companyId) {
      return ctx.error("notFound", "Purchase return order not found");
    }

    try {
      await service.confirmPurchaseReturnOrder(
        ctx.asSystem.pg,
        { id: purchaseReturnOrderId, companyId },
        userId
      );
    } catch (err) {
      return service.refusedBy(ctx, err, "Failed to confirm return order");
    }

    try {
      const pdf = await renderPurchaseReturnOrderPdf(ctx.asCaller.supabase, {
        companyId,
        companyGroupId: ctx.company.groupId,
        purchaseReturnOrderId,
        locale: locale ?? "en-US"
      });
      const fileName = storedDocumentPdfName(
        order.data.purchaseReturnOrderId ?? "",
        datetime.timestamp()
      );
      const path = `${companyId}/purchase-return-order/${purchaseReturnOrderId}/${fileName}`;
      const upload = await storage(system)
        .company(companyId)
        .upload(path, pdf.body, {
          cacheControl: `${12 * 60 * 60}`,
          contentType: "application/pdf",
          upsert: true
        });
      if (upload.error) throw upload.error;
      const document = await upsertDocument(system, {
        path,
        name: fileName,
        size: service.kilobytes(pdf.body),
        sourceDocument: "Purchase Return Order",
        sourceDocumentId: purchaseReturnOrderId,
        readGroups: [userId],
        writeGroups: [userId],
        createdBy: userId,
        companyId
      });
      if (document.error) throw document.error;
    } catch (err) {
      logger.error("Failed to attach the return order PDF", {
        companyId,
        purchaseReturnOrderId,
        error: err
      });
      return {
        purchaseReturnOrderId,
        warning: "Return order confirmed, but the PDF could not be generated"
      };
    }
    return { purchaseReturnOrderId, warning: null };
  }
});

// ── Purchasing planning ─────────────────────────────────────────────────────
/**
 * Order purchasing suggestions at a location.
 *
 * @remarks
 * The purchasing planning page's Order. Each suggested order with a supplier
 * and a period becomes a line on a Planned purchase order: one order per
 * supplier per week (`planningPurchaseOrderWeek`), reusing the supplier's open
 * Draft / Planned order at the location that covers only that week in the
 * supplier's currency, else a new one. An order for an item the purchase
 * order already has on the same date adds to that line. The quantity is
 * raised to the supplier part's minimum; the price is the supplier part's,
 * converted at today's rate (refused for a currency with no rate); the tax is
 * the supplier's. An item whose purchasing is blocked is skipped. The orders
 * raised keep their planning approval bypass, the supply forecast is
 * recorded, and the Order suggestions they answer are settled.
 *
 * Existing lines are changed with `purchasing_updatePlanningPurchaseOrderLine` or
 * `purchasing_applyPlanningActions`, never here. Refused when nothing could be
 * ordered; otherwise the problems are listed in `errors`.
 *
 * @mcp
 */
export const orderPlannedPurchases = defineServiceFn({
  input: z.object({
    locationId: z.string(),
    items: z
      .array(
        z.object({ id: z.string(), orders: z.array(plannedOrderValidator) })
      )
      .min(1, "No items were provided to create purchase orders")
  }),
  permission: { create: "purchasing" },

  async run(ctx, { locationId, items: itemsToOrder }) {
    const client = ctx.asSystem.supabase;
    const companyId = ctx.company.id;
    const companyGroupId = ctx.company.groupId;
    const userId = ctx.auditUserId;

    // `order` only creates PO lines. An existing line is changed through
    // `updateLine` or Apply, which carry the status, promised-date and
    // tax-pair guards; a stale client naming one here would get a duplicate.
    if (
      itemsToOrder.some((item) =>
        item.orders.some((o) => o.existingLineId || o.existingId)
      )
    ) {
      return ctx.error(
        "validation",
        "Existing orders are changed from the Open Orders list"
      );
    }

    const supplierIds = new Set<string>();
    const itemIds = new Set<string>();
    const periodIds = new Set<string>();
    const allSupplyForecasts: Array<{
      itemId: string;
      locationId: string;
      sourceType: "Purchase Order";
      forecastQuantity: number;
      periodId: string;
      companyId: string;
      createdBy: string;
      updatedBy: string;
    }> = [];

    // Group new orders by supplier; below, each supplier's orders are split
    // again by week, so a supplier gets one PO per week.
    type OrderEntry = {
      itemId: string;
      order: (typeof itemsToOrder)[0]["orders"][0];
    };
    const ordersBySupplier = new Map<string, OrderEntry[]>();
    const errors: string[] = [];
    // The (item, week) of every order that became a PO line, so the Order
    // suggestions it answers leave the worklist now, not at the next run.
    const ordered: { itemId: string; periodId: string }[] = [];

    for (const item of itemsToOrder) {
      itemIds.add(item.id);
      let itemHasUsableOrder = false;
      for (const order of item.orders) {
        if (order.supplierId) supplierIds.add(order.supplierId);
        if (order.periodId) periodIds.add(order.periodId);
        if (order.supplierId && order.periodId) {
          ordersBySupplier.set(order.supplierId, [
            ...(ordersBySupplier.get(order.supplierId) ?? []),
            { itemId: item.id, order }
          ]);
          itemHasUsableOrder = true;
        }
      }
      if (!itemHasUsableOrder) {
        errors.push(
          `Item ${item.id} skipped: no order had both a supplier and a period (check that the item has a preferred supplier)`
        );
      }
    }

    // Every id comes from the caller and the writes bypass RLS: the location
    // and items must be this company's (supplyForecast upserts on
    // (itemId, locationId, periodId) alone).
    const location = await refuseUnlessOwned(ctx, "location", {
      id: locationId
    });
    if (location) return location;
    const ownedItems = await client
      .from("item")
      .select("id")
      .in("id", Array.from(itemIds))
      .eq("companyId", companyId);
    if (ownedItems.error || (ownedItems.data?.length ?? 0) !== itemIds.size) {
      logger.error("Planning order references records outside company", {
        companyId,
        userId,
        locationId,
        itemIds: Array.from(itemIds),
        error: ownedItems.error
      });
      return ctx.error("notFound", "Item not found");
    }

    const [suppliers, supplierParts, company, currencies, exchangeRates] =
      await Promise.all([
        client
          .from("supplier")
          .select("id, name, taxPercent, currencyCode")
          .in("id", Array.from(supplierIds))
          .eq("companyId", companyId),
        client
          .from("supplierPart")
          .select("*")
          .in("itemId", Array.from(itemIds))
          .eq("companyId", companyId),
        client
          .from("company")
          .select("id, baseCurrencyCode")
          .eq("id", companyId)
          .single(),
        client
          .from("currencies")
          .select("code, decimalPlaces")
          .eq("companyGroupId", companyGroupId),
        // Today's rate for each currency a supplier part is priced in.
        client.rpc("get_exchange_rates", { p_company_id: companyId })
      ]);
    if (suppliers.error) {
      return ctx.error(
        "internal",
        "Failed to retrieve supplier information from database",
        suppliers.error
      );
    }
    if (supplierParts.error) {
      return ctx.error(
        "internal",
        "Failed to retrieve supplier part information from database",
        supplierParts.error
      );
    }
    if (company.error) {
      return ctx.error(
        "internal",
        "Failed to retrieve company information from database",
        company.error
      );
    }

    const suppliersById = new Map(
      suppliers.data.map((supplier) => [supplier.id, supplier])
    );
    const baseCurrencyCode = company.data.baseCurrencyCode ?? "USD";
    const exchangeRateByCurrency = new Map(
      (exchangeRates.data ?? []).map((rate) => [rate.currencyCode, rate.rate])
    );
    // Settlement amounts round at the currency's own decimals, so the planned
    // order carries a real money value rather than a raw product.
    const currencyDecimals = new Map(
      currencies.data?.map((c) => [c.code, c.decimalPlaces]) ?? []
    );

    let processedItems = 0;
    // Readable ids too, so the client can present a clickable toast.
    const poCache = new Map<string, { id: string; readableId: string }>();

    // Whether purchasing is blocked, for every item ordered, in one read.
    const purchasingRows = await client
      .from("itemReplenishment")
      .select("itemId, purchasingBlocked")
      .in("itemId", Array.from(itemIds))
      .eq("companyId", companyId);
    const purchasingByItem = new Map(
      (purchasingRows.data ?? []).map((row) => [row.itemId, row])
    );

    // Weeks are counted from the location's today, as the planning grid's are.
    const asOf = datetime.today(
      await getLocationTimeZone(client, locationId, companyId)
    );

    // Every open PO an order may join, with its lines, in one read: the
    // suppliers' Draft / Planned purchase orders at this location, oldest
    // first. The lines tell which weeks a PO already covers, and which line a
    // same-item, same-date order adds its quantity to.
    const openPurchaseOrders = await client
      .from("purchaseOrder")
      .select(
        "id, purchaseOrderId, supplierId, currencyCode, exchangeRate, createdFromPlanning, purchaseOrderDelivery!inner(locationId), purchaseOrderLine(id, itemId, requiredDate, purchaseQuantity, supplierUnitPrice, supplierShippingCost, taxPercent, supplierTaxAmount)"
      )
      .eq("companyId", companyId)
      .in("supplierId", Array.from(ordersBySupplier.keys()))
      .eq("purchaseOrderType", "Purchase")
      .in("status", ["Draft", "Planned"])
      .eq("purchaseOrderDelivery.locationId", locationId)
      .order("createdAt", { ascending: true });
    if (openPurchaseOrders.error) {
      return ctx.error(
        "internal",
        "Failed to retrieve open purchase orders from database",
        openPurchaseOrders.error
      );
    }

    const candidatePurchaseOrders = openPurchaseOrders.data.map((po) => ({
      id: po.id,
      purchaseOrderId: po.purchaseOrderId,
      supplierId: po.supplierId,
      currencyCode: po.currencyCode,
      exchangeRate: po.exchangeRate ?? 1,
      createdFromPlanning: po.createdFromPlanning,
      purchaseOrderLine: po.purchaseOrderLine ?? []
    }));

    // The POs this call raised, and the planning POs it added to: their
    // approval bypass (`createdFromPlanning`) is restored once their lines are
    // written, since the shared line writer clears it on any change. A Draft /
    // Planned PO someone created by hand stays unflagged.
    const planningPurchaseOrderIds = new Set<string>();

    for (const [supplierId, ordersForSupplier] of ordersBySupplier) {
      const supplier = suppliersById.get(supplierId);
      if (!supplier) {
        errors.push(`Supplier ${supplierId} not found`);
        continue;
      }

      const currencyCode = supplier.currencyCode ?? baseCurrencyCode;
      const decimals = currencyDecimals.get(currencyCode) ?? SCALE;

      // One PO per supplier per week, so each week's PO is finalized and sent
      // on its own and the later weeks stay Planned, where MRP can still move,
      // resize or cancel them.
      const ordersByWeek = new Map<string, OrderEntry[]>();
      for (const entry of ordersForSupplier) {
        const week = planningPurchaseOrderWeek(entry.order.dueDate, asOf);
        ordersByWeek.set(week, [...(ordersByWeek.get(week) ?? []), entry]);
      }

      for (const [week, ordersInGroup] of ordersByWeek) {
        let purchaseOrder = findPlanningPurchaseOrder(
          candidatePurchaseOrders,
          { supplierId, currencyCode, week },
          asOf
        );

        if (purchaseOrder) {
          if (purchaseOrder.createdFromPlanning) {
            planningPurchaseOrderIds.add(purchaseOrder.id);
          }
        } else {
          const createPO = await service.insertPurchaseOrder(client, {
            status: "Planned",
            supplierId,
            purchaseOrderType: "Purchase",
            currencyCode,
            locationId,
            companyId,
            companyGroupId,
            createdBy: userId
          });
          if (createPO.error || !createPO.data) {
            logger.error("Failed to create PO for supplier", {
              companyId,
              locationId,
              supplierId,
              week,
              error: createPO.error
            });
            errors.push(
              `Failed to create PO for supplier ${supplierId}: ${createPO.error?.message ?? "no data returned"}`
            );
            continue;
          }
          purchaseOrder = {
            id: createPO.data.id,
            purchaseOrderId: createPO.data.purchaseOrderId,
            supplierId,
            currencyCode,
            exchangeRate: createPO.data.exchangeRate,
            createdFromPlanning: true,
            purchaseOrderLine: []
          };
          planningPurchaseOrderIds.add(createPO.data.id);
          candidatePurchaseOrders.push(purchaseOrder);
        }

        const purchaseOrderId = purchaseOrder.id;
        poCache.set(`${supplierId}:${week}`, {
          id: purchaseOrderId,
          readableId: purchaseOrder.purchaseOrderId ?? purchaseOrderId
        });

        for (const { itemId, order } of ordersInGroup) {
          const supplierPart = supplierParts.data.find(
            (sp) => sp.itemId === itemId && sp.supplierId === supplierId
          );

          const purchasingError =
            purchasingRows.error ??
            (purchasingByItem.has(itemId)
              ? null
              : { message: "No replenishment record" });
          if (purchasingError) {
            errors.push(
              `Failed to retrieve purchasing data for item ${itemId}: ${purchasingError.message}`
            );
            continue;
          }
          if (purchasingByItem.get(itemId)?.purchasingBlocked) {
            errors.push(`Purchasing is blocked for item ${itemId}`);
            continue;
          }

          const minimumOrderQuantity = supplierPart?.minimumOrderQuantity ?? 0;
          const adjustedQuantity =
            minimumOrderQuantity > 0 && order.quantity < minimumOrderQuantity
              ? minimumOrderQuantity
              : order.quantity;

          // An order for an item the PO already has on the same date adds to
          // that line. Orders for different dates stay on separate lines so
          // each keeps its own required date.
          const requiredDate = order.dueDate ?? null;
          const existing = purchaseOrder.purchaseOrderLine.find(
            (line) =>
              line.itemId === itemId && line.requiredDate === requiredDate
          );

          if (existing) {
            const purchaseQuantity =
              (existing.purchaseQuantity ?? 0) + adjustedQuantity;
            // The extended price follows the quantity on its own; the tax
            // amount is stored, so it is restated at the line's rate.
            const tax = taxPairForQuantity(
              existing,
              purchaseQuantity,
              decimals
            );
            const updateLine = await client
              .from("purchaseOrderLine")
              .update({
                purchaseQuantity,
                taxPercent: tax.percent,
                supplierTaxAmount: tax.amount,
                updatedBy: userId
              })
              .eq("id", existing.id)
              .eq("companyId", companyId);
            if (updateLine.error) {
              errors.push(
                `Failed to update PO line for item ${itemId}: ${updateLine.error.message}`
              );
              continue;
            }
            existing.purchaseQuantity = purchaseQuantity;
            existing.taxPercent = tax.percent;
            existing.supplierTaxAmount = tax.amount;
          } else {
            // The supplier part's price is in its own currency; the line holds
            // the order's, converted at today's rate.
            const partCurrency = supplierPartCurrency(
              supplierPart?.currencyCode,
              baseCurrencyCode
            );
            // Base is always 1, whether or not the group lists it.
            const partRate =
              partCurrency === baseCurrencyCode
                ? 1
                : exchangeRateByCurrency.get(partCurrency);
            if (
              supplierPart?.supplierUnitPrice != null &&
              partCurrency !== currencyCode &&
              !partRate
            ) {
              errors.push(
                `No exchange rate for ${partCurrency}: set one in Accounting → Exchange Rates`
              );
              continue;
            }
            const supplierUnitPrice =
              supplierPart?.supplierUnitPrice != null
                ? convertUnitPrice(
                    supplierPart.supplierUnitPrice,
                    { currencyCode: partCurrency, exchangeRate: partRate ?? 1 },
                    { currencyCode, exchangeRate: purchaseOrder.exchangeRate }
                  )
                : 0;
            const taxPercent = supplier.taxPercent ?? 0;
            // supplier.taxPercent is a 0..1 fraction; the amount follows the
            // canonical denominator. Shipping is 0 on this path.
            const supplierTaxAmount = applyRate(
              taxableBase(supplierUnitPrice, adjustedQuantity, 0),
              taxPercent,
              decimals
            );
            const createLine = await service.upsertPurchaseOrderLine(client, {
              purchaseOrderId,
              itemId,
              description: order.description,
              purchaseOrderLineType: "Part",
              purchaseQuantity: adjustedQuantity,
              purchaseUnitOfMeasureCode:
                supplierPart?.supplierUnitOfMeasureCode ??
                order.unitOfMeasureCode,
              inventoryUnitOfMeasureCode: order.unitOfMeasureCode,
              conversionFactor: supplierPart?.conversionFactor ?? 1,
              supplierUnitPrice,
              exchangeRate: purchaseOrder.exchangeRate,
              taxPercent,
              supplierTaxAmount,
              supplierShippingCost: 0,
              requiredDate: order.dueDate ?? undefined,
              locationId,
              companyId,
              createdBy: userId
            });
            if (createLine.error) {
              errors.push(
                `Failed to create PO line for item ${itemId}: ${createLine.error.message}`
              );
              continue;
            }
            purchaseOrder.purchaseOrderLine.push({
              id: createLine.data.id,
              itemId,
              requiredDate,
              purchaseQuantity: adjustedQuantity,
              supplierUnitPrice,
              supplierShippingCost: 0,
              taxPercent,
              supplierTaxAmount
            });
          }

          processedItems++;
          ordered.push({ itemId, periodId: order.periodId });
          allSupplyForecasts.push({
            itemId,
            locationId,
            sourceType: "Purchase Order",
            forecastQuantity:
              order.quantity * (supplierPart?.conversionFactor ?? 1),
            periodId: order.periodId,
            companyId,
            createdBy: userId,
            updatedBy: userId
          });
        }
      }
    }

    if (allSupplyForecasts.length > 0) {
      const forecasts = await client
        .from("supplyForecast")
        .upsert(service.deduplicateForecasts(allSupplyForecasts), {
          onConflict: "itemId,locationId,periodId",
          ignoreDuplicates: false
        });
      if (forecasts.error) {
        const message = `Failed to insert supply forecasts: ${forecasts.error.message}`;
        logger.error(message, { companyId, locationId });
        errors.push(message);
      }
    }

    if (planningPurchaseOrderIds.size > 0) {
      const flagged = await client
        .from("purchaseOrder")
        .update({ createdFromPlanning: true })
        .in("id", [...planningPurchaseOrderIds])
        .eq("companyId", companyId);
      if (flagged.error) {
        // The orders stand; they go through approval like any other PO.
        logger.error("Failed to mark planning purchase orders", {
          companyId,
          purchaseOrderIds: [...planningPurchaseOrderIds],
          error: flagged.error
        });
      }
    }

    const settled = await settleNewSupplyPlanningActions(ctx.asSystem.pg, {
      companyId,
      locationId,
      userId,
      type: "Order",
      ordered
    });
    if (settled.error) {
      // The PO lines stand; the suggestions clear on the next MRP run.
      logger.error("Failed to settle ordered planning actions", {
        companyId,
        locationId,
        error: settled.error
      });
    }

    if (errors.length > 0 && processedItems === 0) {
      logger.error("Failed to process any planning orders", {
        companyId,
        locationId,
        itemIds: Array.from(itemIds),
        supplierIds: Array.from(supplierIds),
        periodIds: Array.from(periodIds),
        errors
      });
      return ctx.error(
        "rule",
        `Failed to process any items. Errors: ${errors.slice(0, 3).join("; ")}${
          errors.length > 3 ? ` and ${errors.length - 3} more...` : ""
        }`
      );
    }

    return {
      message:
        processedItems === itemsToOrder.length
          ? `Successfully processed all ${processedItems} items`
          : `Processed ${processedItems} of ${itemsToOrder.length} items. ${
              errors.length
            } errors occurred: ${errors.slice(0, 2).join("; ")}${
              errors.length > 2 ? "..." : ""
            }`,
      processedItems,
      totalItems: itemsToOrder.length,
      // Each supplier week has its own PO; the dedupe is only a guard.
      purchaseOrders: Array.from(
        new Map(Array.from(poCache.values()).map((po) => [po.id, po])).values()
      ),
      errors: errors.length > 0 ? errors : undefined
    };
  }
});

/**
 * Change the quantity or due date of a purchase order line from planning.
 *
 * @remarks
 * The planning drawer's Open Orders cell. Only a line at `locationId`, on a
 * Draft or Planned order (not in approval, not sent), and for a due date only
 * when the supplier has promised none. The tax pair is restated with the
 * quantity.
 *
 * @mcp
 */
export const updatePlanningPurchaseOrderLine = defineServiceFn({
  input: z.object({
    locationId: z.string(),
    line: z.discriminatedUnion("field", [
      z.object({
        id: z.string().min(1),
        field: z.literal("quantity"),
        value: z.number().positive()
      }),
      z.object({
        id: z.string().min(1),
        field: z.literal("dueDate"),
        value: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
      })
    ])
  }),
  permission: { update: "purchasing" },

  async run(ctx, { locationId, line }) {
    const companyId = ctx.company.id;
    const committed = () =>
      ctx.error(
        "conflict",
        "This purchase order is in approval or has been sent to the supplier. Change it on the order."
      );

    const target = await ctx.asSystem.supabase
      .from("purchaseOrderLine")
      .select(
        "id, locationId, promisedDate, purchaseOrder!inner(id, status, purchaseOrderDelivery(receiptPromisedDate))"
      )
      .eq("id", line.id)
      .eq("companyId", companyId)
      .maybeSingle();
    if (target.error || !target.data) {
      return ctx.error(
        "notFound",
        "Purchase order line not found",
        target.error
      );
    }
    // The drawer lists one location's orders; a request for another
    // location's line did not come from it.
    if (target.data.locationId !== locationId) {
      return ctx.error(
        "conflict",
        "This purchase order line is for another location."
      );
    }
    if (
      !isPurchaseOrderEditableFromPlanning(target.data.purchaseOrder?.status)
    ) {
      return committed();
    }
    if (
      line.field === "dueDate" &&
      service.promisedDateOf({
        promisedDate: target.data.promisedDate,
        receiptPromisedDate:
          target.data.purchaseOrder?.purchaseOrderDelivery?.receiptPromisedDate
      }) !== null
    ) {
      return ctx.error(
        "conflict",
        "The supplier has promised a date for this line. Change it on the order."
      );
    }

    const saved = await service.updatePurchaseOrderLineSchedule(
      ctx.asSystem.supabase,
      ctx.asSystem.pg,
      {
        lineId: target.data.id,
        companyId,
        companyGroupId: ctx.company.groupId,
        userId: ctx.auditUserId,
        ...(line.field === "quantity"
          ? { purchaseQuantity: line.value }
          : { requiredDate: line.value })
      }
    );
    if (saved.error) {
      return ctx.error(
        "internal",
        "Failed to update purchase order line",
        saved.error
      );
    }
    // Sent or put in approval after the status check above.
    if (!saved.updated) return committed();
    return { message: "Updated purchase order line" };
  }
});

const PLANNING_ACTION_TYPE_OF: Record<string, string> = {
  expedite: "Expedite",
  defer: "Defer",
  increase: "Increase",
  decrease: "Decrease",
  cancel: "Cancel"
};
const PLANNING_CHANGE_TYPES = new Set(Object.values(PLANNING_ACTION_TYPE_OF));

/** A planning worklist's ids: one each, at least one. */
const planningActionIds = z
  .array(z.string().min(1))
  .min(1)
  .transform((ids) => [...new Set(ids)]);

type PlanningLine = {
  id: string;
  purchaseOrderId: string;
  conversionFactor: number | null;
  promisedDate: string | null;
  purchaseOrderStatus:
    | Database["public"]["Enums"]["purchaseOrderStatus"]
    | null;
  receiptPromisedDate: string | null;
};

/**
 * Apply MRP's suggestions to their purchase order lines.
 *
 * @remarks
 * Each Open planning action is applied as it was suggested (the type, line,
 * quantity and date come from the stored action, never the caller):
 * Expedite and Defer move the line's required date, Increase and Decrease
 * its quantity, Cancel deletes the line (needs `delete: purchasing`). `type`
 * `apply` takes any of them; the others only their own. An action whose
 * order is in approval or sent, or whose date the supplier promised, is
 * listed in `requiresManualAction` to review on the order. Everything is
 * written in one transaction. `success` is false when an action failed or
 * nothing could be applied.
 *
 * @mcp
 */
export const applyPlanningActions = defineServiceFn({
  input: z.object({
    planningActionIds,
    type: z.enum([
      "apply",
      "expedite",
      "defer",
      "increase",
      "decrease",
      "cancel"
    ])
  }),
  permission: { update: "purchasing" },

  async run(ctx, { planningActionIds: ids, type }) {
    const db = ctx.asSystem.pg;
    const companyId = ctx.company.id;
    const applied: string[] = [];
    const requiresManualAction: {
      id: string;
      purchaseOrderId: string | null;
    }[] = [];
    const errors: string[] = [];

    // Two reads for the whole batch decide what is eligible, then ONE
    // transaction applies all of it.
    const actionRows = await getPlanningActionsByIds(db, { ids, companyId });
    if (actionRows.error) {
      return ctx.error(
        "internal",
        "Failed to read planning actions",
        actionRows.error
      );
    }
    const rowById = new Map(actionRows.data.map((row) => [row.id, row]));

    const eligible: {
      planningActionId: string;
      row: (typeof actionRows.data)[number];
    }[] = [];
    for (const planningActionId of ids) {
      const row = rowById.get(planningActionId);
      if (!row) {
        errors.push(`Planning action ${planningActionId} not found`);
        continue;
      }
      if (row.status !== "Open") {
        errors.push(`Planning action ${planningActionId} is not open`);
        continue;
      }
      if (
        type === "apply"
          ? !PLANNING_CHANGE_TYPES.has(row.type)
          : PLANNING_ACTION_TYPE_OF[type] !== row.type
      ) {
        errors.push(
          type === "apply"
            ? `Planning action ${planningActionId} is a ${row.type}, which Apply cannot batch`
            : `Planning action ${planningActionId} is a ${row.type}, not ${PLANNING_ACTION_TYPE_OF[type]}`
        );
        continue;
      }
      if (!row.purchaseOrderLineId) {
        errors.push(
          `Planning action ${planningActionId} does not target a purchase order line`
        );
        continue;
      }
      eligible.push({ planningActionId, row });
    }

    // One statement: the id list goes to Postgres as a parameter, never into
    // a PostgREST URL.
    const lineIds = [
      ...new Set(eligible.map(({ row }) => row.purchaseOrderLineId!))
    ];
    let lineById: Map<string, PlanningLine>;
    try {
      const lines =
        lineIds.length > 0
          ? await db
              .selectFrom("purchaseOrderLine as pol")
              .innerJoin("purchaseOrder as po", (join) =>
                join
                  .onRef("po.id", "=", "pol.purchaseOrderId")
                  .on("po.companyId", "=", companyId)
              )
              .leftJoin("purchaseOrderDelivery as pod", "pod.id", "po.id")
              .select([
                "pol.id",
                "pol.purchaseOrderId",
                "pol.conversionFactor",
                "pol.promisedDate",
                "po.status as purchaseOrderStatus",
                "pod.receiptPromisedDate"
              ])
              .where("pol.id", "in", lineIds)
              .where("pol.companyId", "=", companyId)
              .execute()
          : [];
      lineById = new Map(lines.map((line) => [line.id, line]));
    } catch (err) {
      return ctx.error(
        "internal",
        "Failed to read the planning actions' purchase order lines",
        err
      );
    }

    const mayDeleteLines = ctx.can({ delete: "purchasing" });
    const toClaim: {
      planningActionId: string;
      row: (typeof eligible)[number]["row"];
      line: PlanningLine;
    }[] = [];
    for (const { planningActionId, row } of eligible) {
      const line = lineById.get(row.purchaseOrderLineId!);
      if (!line) {
        errors.push(
          `Purchase order line for planning action ${planningActionId} not found`
        );
        continue;
      }
      const datePromised =
        (row.type === "Expedite" || row.type === "Defer") &&
        service.promisedDateOf(line) !== null;
      if (
        !isPurchaseOrderEditableFromPlanning(line.purchaseOrderStatus) ||
        datePromised
      ) {
        // In approval or sent, or a date the supplier promised (which the
        // required date cannot move): review on the order instead.
        requiresManualAction.push({
          id: planningActionId,
          purchaseOrderId: line.purchaseOrderId
        });
        continue;
      }
      if (row.type === "Cancel" && !mayDeleteLines) {
        errors.push(
          `Planning action ${planningActionId} deletes a purchase order line, which needs delete permission`
        );
        continue;
      }
      toClaim.push({ planningActionId, row, line });
    }

    let outcome: Awaited<
      ReturnType<typeof service.applyPurchasingPlanningActions>
    >;
    try {
      outcome = await service.applyPurchasingPlanningActions(db, {
        companyId,
        companyGroupId: ctx.company.groupId,
        userId: ctx.auditUserId,
        actions: toClaim.map(({ planningActionId, row, line }) => ({
          planningActionId,
          type: row.type as
            | "Expedite"
            | "Defer"
            | "Increase"
            | "Decrease"
            | "Cancel",
          lineId: line.id,
          purchaseOrderId: line.purchaseOrderId,
          suggestedDate: row.suggestedDate ?? null,
          suggestedQuantity:
            row.suggestedQuantity === null ||
            row.suggestedQuantity === undefined
              ? null
              : Number(row.suggestedQuantity)
        }))
      });
    } catch (err) {
      return ctx.error(
        "internal",
        `Failed to apply planning actions: ${
          err instanceof Error ? err.message : "unknown error"
        }`,
        err
      );
    }
    applied.push(...outcome.applied);
    requiresManualAction.push(...outcome.refused);
    for (const id of outcome.alreadyApplied) {
      errors.push(`Planning action ${id} was already applied`);
    }
    for (const failure of outcome.failed) {
      errors.push(`Planning action ${failure.id}: ${failure.message}`);
    }

    // Committed targets are not failures, but "Applied 0" as a success is a
    // lie: name the manual-review count, and report success only when
    // something was applied (or nothing needed review).
    const manualCount = requiresManualAction.length;
    const messageParts = [
      `Applied ${applied.length} planning action${applied.length === 1 ? "" : "s"}`
    ];
    if (manualCount > 0) {
      messageParts.push(
        `${manualCount} target${manualCount === 1 ? " is" : "s are"} committed — review on the order`
      );
    }
    if (errors.length > 0) messageParts.push(`${errors.length} failed`);
    return {
      success:
        errors.length === 0 && !(applied.length === 0 && manualCount > 0),
      message: messageParts.join("; "),
      applied,
      requiresManualAction,
      errors: errors.length > 0 ? errors : undefined
    };
  }
});
/**
 * Dismiss purchasing suggestions.
 *
 * @remarks
 * Hides Open Buy planning actions from the worklist until their need changes
 * materially. An action applied or changed since it was read is skipped;
 * refused when none changed.
 *
 * @mcp
 */
export const dismissPurchasingPlanningActions = defineServiceFn({
  input: z.object({ planningActionIds }),
  permission: { update: "purchasing" },

  async run(ctx, { planningActionIds: ids }) {
    const result = await dismissPlanningActions(ctx.asSystem.pg, {
      ids,
      companyId: ctx.company.id,
      userId: ctx.auditUserId,
      kind: "Buy"
    });
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to dismiss planning actions",
        result.error
      );
    }
    return service.worklistChange(
      ctx,
      "Dismissed",
      result.data?.length ?? 0,
      ids.length
    );
  }
});

/**
 * Reopen dismissed purchasing suggestions.
 *
 * @remarks
 * Puts dismissed Buy planning actions back on the worklist. An action that
 * changed since it was read is skipped; refused when none changed.
 *
 * @mcp
 */
export const reopenPurchasingPlanningActions = defineServiceFn({
  input: z.object({ planningActionIds }),
  permission: { update: "purchasing" },

  async run(ctx, { planningActionIds: ids }) {
    const result = await reopenDismissedPlanningActions(ctx.asSystem.pg, {
      ids,
      companyId: ctx.company.id,
      userId: ctx.auditUserId,
      kind: "Buy"
    });
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to reopen planning actions",
        result.error
      );
    }
    return service.worklistChange(
      ctx,
      "Reopened",
      result.data?.length ?? 0,
      ids.length
    );
  }
});

/**
 * Assign purchasing suggestions to a person.
 *
 * @remarks
 * Sets the owner of Buy planning actions, which MRP then keeps; no
 * `assignee` clears it. The assignee must be an active employee of the
 * company. An action that changed since it was read is skipped; refused when
 * none changed.
 *
 * @mcp
 */
export const assignPurchasingPlanningActions = defineServiceFn({
  input: z.object({ planningActionIds, assignee: z.string().optional() }),
  permission: { update: "purchasing" },

  async run(ctx, { planningActionIds: ids, assignee }) {
    const companyId = ctx.company.id;
    if (
      assignee &&
      !(await isActiveCompanyEmployee(
        ctx.asSystem.supabase,
        companyId,
        assignee
      ))
    ) {
      return ctx.error("validation", "Choose an employee of this company");
    }
    const result = await assignPlanningActions(ctx.asSystem.pg, {
      ids,
      companyId,
      assignee: assignee || null,
      userId: ctx.auditUserId,
      kind: "Buy"
    });
    if (result.error) {
      return ctx.error(
        "internal",
        "Failed to assign planning actions",
        result.error
      );
    }
    return service.worklistChange(
      ctx,
      "Assigned",
      result.data?.length ?? 0,
      ids.length
    );
  }
});
/**
 * Convert supplier quote to order
 *
 * @mcp
 */
export const convertSupplierQuoteToOrder = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    selectedLines: z.record(z.string(), z.unknown())
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.convertSupplierQuoteToOrder(
        ctx.asCaller.supabase,
        ctx.asSystem.pg,
        payload(ctx, input).withUser().forUpdate() as never
      )
    );
  }
});

/**
 * Delete purchase order line
 *
 * @mcp destructive
 */
export const deletePurchaseOrderLine = defineServiceFn({
  input: z.looseObject({ purchaseOrderLineId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deletePurchaseOrderLine(
        ctx.asCaller.supabase,
        input.purchaseOrderLineId as never
      )
    );
  }
});

/**
 * Duplicate purchase order
 *
 * @mcp
 */
export const duplicatePurchaseOrder = defineServiceFn({
  input: z.looseObject({ sourcePurchaseOrderId: z.string() }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.duplicatePurchaseOrder(
        ctx.asCaller.supabase,
        payload(ctx, input).withGroup().withUser().forUpsert() as never
      )
    );
  }
});

/**
 * Delete supplier
 *
 * @mcp destructive
 */
export const deleteSupplier = defineServiceFn({
  input: z.looseObject({ supplierId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplier(
        ctx.asCaller.supabase,
        input.supplierId as never
      )
    );
  }
});

/**
 * Delete supplier contact
 *
 * @mcp destructive
 */
export const deleteSupplierContact = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    supplierContactId: z.string()
  }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplierContact(
        ctx.asCaller.supabase,
        input.supplierId as never,
        input.supplierContactId as never
      )
    );
  }
});

/**
 * Delete supplier location
 *
 * @mcp destructive
 */
export const deleteSupplierLocation = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    supplierLocationId: z.string()
  }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplierLocation(
        ctx.asCaller.supabase,
        input.supplierId as never,
        input.supplierLocationId as never
      )
    );
  }
});

/**
 * Delete supplier bank account
 *
 * @mcp destructive
 */
export const deleteSupplierBankAccount = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { delete: "accounting" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplierBankAccount(
        ctx.asCaller.supabase,
        input.id as never
      )
    );
  }
});

/**
 * Lists a supplier's bank accounts
 *
 * @mcp read
 */
export const getSupplierBankAccounts = defineServiceFn({
  input: z.looseObject({ supplierId: z.string() }),
  permission: { view: "accounting" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierBankAccounts(
        ctx.asCaller.supabase,
        input.supplierId as never
      )
    );
  }
});

/**
 * Create a supplier bank account
 *
 * @remarks
 * Upsert supplier bank account
 *
 * @mcp
 */
export const createSupplierBankAccount = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string().min(1),
    name: z.string().min(1),
    accountHolderName: z.string().optional(),
    bankName: z.string().min(1),
    bankAddress: z.string().min(1),
    countryCode: z.string().min(1),
    currencyCode: z.string().optional(),
    accountNumber: z.string().optional(),
    bankCode: z.string().optional(),
    swiftBic: z.string().optional(),
    notes: z.string().optional(),
    customFields: z.unknown().optional(),
    id: z
      .string()
      .describe("Send to update that record; omit to create a new one.")
      .optional()
  }),
  permission: { create: "accounting" },
  async run(ctx, input) {
    return await service.upsertSupplierBankAccount(
      ctx.asSystem.pg,
      payload(ctx, input).forCreate() as never
    );
  }
});

/**
 * Update a supplier bank account
 *
 * @remarks
 * Upsert supplier bank account
 *
 * @mcp
 */
export const updateSupplierBankAccount = defineServiceFn({
  input: z
    .looseObject({
      supplierId: z.string().min(1),
      name: z.string().min(1),
      accountHolderName: z.string().optional(),
      bankName: z.string().min(1),
      bankAddress: z.string().min(1),
      countryCode: z.string().min(1),
      currencyCode: z.string().optional(),
      accountNumber: z.string().optional(),
      bankCode: z.string().optional(),
      swiftBic: z.string().optional(),
      notes: z.string().optional(),
      customFields: z.unknown().optional(),
      id: z
        .string()
        .describe("Send to update that record; omit to create a new one.")
        .optional()
    })
    .required({ id: true }),
  permission: { update: "accounting" },
  async run(ctx, input) {
    return await service.upsertSupplierBankAccount(
      ctx.asSystem.pg,
      payload(ctx, input).forUpdate() as never
    );
  }
});

/**
 * Delete supplier process
 *
 * @mcp destructive
 */
export const deleteSupplierProcess = defineServiceFn({
  input: z.looseObject({ supplierProcessId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplierProcess(
        ctx.asCaller.supabase,
        input.supplierProcessId as never
      )
    );
  }
});

/**
 * Delete supplier quote
 *
 * @mcp destructive
 */
export const deleteSupplierQuote = defineServiceFn({
  input: z.looseObject({ supplierQuoteId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplierQuote(
        ctx.asCaller.supabase,
        input.supplierQuoteId as never
      )
    );
  }
});

/**
 * Delete supplier quote line
 *
 * @mcp destructive
 */
export const deleteSupplierQuoteLine = defineServiceFn({
  input: z.looseObject({ id: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplierQuoteLine(
        ctx.asCaller.supabase,
        input.id as never
      )
    );
  }
});

/**
 * Delete supplier type
 *
 * @mcp destructive
 */
export const deleteSupplierType = defineServiceFn({
  input: z.looseObject({ supplierTypeId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteSupplierType(
        ctx.asCaller.supabase,
        input.supplierTypeId as never
      )
    );
  }
});

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

/**
 * Get who approved a purchase order and when.
 *
 * @remarks
 * Reads the order's latest approval request that was not cancelled. When it
 * is Approved, answers the approver (`approvedBy` is the name, `approvedById`
 * the user id) and `approvedDate`, the business day of the decision in the
 * company's timezone. All three are null when the order was never approved,
 * is waiting on a decision, or its latest request was rejected.
 *
 * @param purchaseOrderId - The purchase order's id (`po_…`), not its number.
 * @mcp read
 */
export const getPurchaseOrderApproval = defineServiceFn({
  input: z.object({ purchaseOrderId: z.string().min(1) }),
  permission: { view: "purchasing" },
  async run(ctx, { purchaseOrderId }) {
    // approvalRequest has no RLS policies: prove the caller can see the order.
    const order = await ctx.asCaller.supabase
      .from("purchaseOrder")
      .select("id")
      .eq("id", purchaseOrderId)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (order.error) {
      return ctx.error(
        "internal",
        "Failed to load purchase order",
        order.error
      );
    }
    if (!order.data) {
      return ctx.error("notFound", "Purchase order not found");
    }

    const approval = await service.getPurchaseOrderApproval(
      ctx.asSystem.supabase,
      {
        companyId: ctx.company.id,
        purchaseOrderId,
        timezone: await getCompanyTimeZone(
          ctx.asSystem.supabase,
          ctx.company.id
        )
      }
    );
    return {
      purchaseOrderId,
      approvedBy: approval?.approvedBy ?? null,
      approvedById: approval?.approvedById ?? null,
      approvedDate: approval?.approvedDate ?? null
    };
  }
});

/**
 * Get purchase orders
 *
 * @mcp read
 */
export const getPurchaseOrders = 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(),
    status: z.enum(purchaseOrderStatusType).nullable().optional(),
    supplierId: z.string().nullable().optional()
  }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getPurchaseOrders(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get purchase order delivery
 *
 * @mcp read
 */
export const getPurchaseOrderDelivery = defineServiceFn({
  input: z.looseObject({ purchaseOrderId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchaseOrderDelivery(
        ctx.asCaller.supabase,
        input.purchaseOrderId as never
      )
    );
  }
});

/**
 * Get purchase order payment
 *
 * @mcp read
 */
export const getPurchaseOrderPayment = defineServiceFn({
  input: z.looseObject({ purchaseOrderId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchaseOrderPayment(
        ctx.asCaller.supabase,
        input.purchaseOrderId as never
      )
    );
  }
});

/**
 * Get purchase order lines
 *
 * @mcp read
 */
export const getPurchaseOrderLines = defineServiceFn({
  input: z.looseObject({ purchaseOrderId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchaseOrderLines(
        ctx.asCaller.supabase,
        input.purchaseOrderId as never
      )
    );
  }
});

/**
 * Get purchase order line
 *
 * @mcp read
 */
export const getPurchaseOrderLine = defineServiceFn({
  input: z.looseObject({ purchaseOrderLineId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchaseOrderLine(
        ctx.asCaller.supabase,
        input.purchaseOrderLineId as never
      )
    );
  }
});

/**
 * Get purchasing documents assigned to me
 *
 * @mcp read
 */
export const getPurchasingDocumentsAssignedToMe = defineServiceFn({
  input: z.record(z.string(), z.unknown()),
  permission: { view: "purchasing" },
  async run(ctx) {
    return await service.getPurchasingDocumentsAssignedToMe(
      ctx.asCaller.supabase,
      ctx.auditUserId,
      ctx.company.id
    );
  }
});

/**
 * Get purchasing planning
 *
 * @mcp read
 */
export const getPurchasingPlanning = defineServiceFn({
  input: z.looseObject({
    locationId: z.string(),
    periods: z.array(z.string()),
    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(),
    asOf: z.string(),
    actionTypes: z.array(z.string()).optional(),
    actionAssignees: z.array(z.string()).optional()
  }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getPurchasingPlanning(
        ctx.asCaller.supabase,
        input.locationId as never,
        ctx.company.id,
        payload(ctx, input.periods).build() as never,
        payload(ctx, input).build() as never
      )
    );
  }
});

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

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

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

/**
 * Get supplier interaction
 *
 * @mcp read
 */
export const getSupplierInteraction = defineServiceFn({
  input: z.looseObject({ opportunityId: z.string().nullable() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierInteraction(
        ctx.asCaller.supabase,
        input.opportunityId as never
      )
    );
  }
});

/**
 * Get supplier interaction documents
 *
 * @mcp read
 */
export const getSupplierInteractionDocuments = defineServiceFn({
  input: z.looseObject({ interactionId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return await service.getSupplierInteractionDocuments(
      ctx.asCaller.supabase,
      ctx.company.id,
      input.interactionId as never
    );
  }
});

/**
 * Get supplier interaction line documents
 *
 * @mcp read
 */
export const getSupplierInteractionLineDocuments = defineServiceFn({
  input: z.looseObject({ lineId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return await service.getSupplierInteractionLineDocuments(
      ctx.asCaller.supabase,
      ctx.company.id,
      input.lineId as never
    );
  }
});

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

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

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

/**
 * Get supplier processes by process
 *
 * @mcp read
 */
export const getSupplierProcessesByProcess = defineServiceFn({
  input: z.looseObject({ processId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierProcessesByProcess(
        ctx.asCaller.supabase,
        input.processId as never
      )
    );
  }
});

/**
 * Get supplier processes by supplier
 *
 * @mcp read
 */
export const getSupplierProcessesBySupplier = defineServiceFn({
  input: z.looseObject({ supplierId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierProcessesBySupplier(
        ctx.asCaller.supabase,
        input.supplierId as never
      )
    );
  }
});

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

/**
 * Get supplier quote by external link id
 *
 * @mcp read
 */
export const getSupplierQuoteByExternalLinkId = defineServiceFn({
  input: z.looseObject({ externalLinkId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierQuoteByExternalLinkId(
        ctx.asCaller.supabase,
        input.externalLinkId as never
      )
    );
  }
});

/**
 * Get supplier quotes
 *
 * @mcp read
 */
export const getSupplierQuotes = 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: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getSupplierQuotes(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get supplier quote line
 *
 * @mcp read
 */
export const getSupplierQuoteLine = defineServiceFn({
  input: z.looseObject({ supplierQuoteLineId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierQuoteLine(
        ctx.asCaller.supabase,
        input.supplierQuoteLineId as never
      )
    );
  }
});

/**
 * Get supplier quote lines
 *
 * @mcp read
 */
export const getSupplierQuoteLines = defineServiceFn({
  input: z.looseObject({ supplierQuoteId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierQuoteLines(
        ctx.asCaller.supabase,
        input.supplierQuoteId as never
      )
    );
  }
});

/**
 * Get supplier quote line prices
 *
 * @mcp read
 */
export const getSupplierQuoteLinePrices = defineServiceFn({
  input: z.looseObject({ supplierQuoteLineId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierQuoteLinePrices(
        ctx.asCaller.supabase,
        input.supplierQuoteLineId as never
      )
    );
  }
});

/**
 * Get supplier quote line prices by quote id
 *
 * @mcp read
 */
export const getSupplierQuoteLinePricesByQuoteId = defineServiceFn({
  input: z.looseObject({ supplierQuoteId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierQuoteLinePricesByQuoteId(
        ctx.asCaller.supabase,
        input.supplierQuoteId as never
      )
    );
  }
});

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

/**
 * Get supplier report contacts
 *
 * @mcp read
 */
export const getSupplierReportContacts = defineServiceFn({
  input: z.looseObject({ supplierIds: z.array(z.string()) }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      ...(await service.getSupplierReportContacts(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input.supplierIds).build() as never
      ))
    );
  }
});

/**
 * Get suppliers
 *
 * @mcp read
 */
export const getSuppliers = 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(),
    type: z.string().nullable().optional(),
    status: z.string().nullable().optional()
  }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getSuppliers(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

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

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

/**
 * Get supplier types
 *
 * @mcp read
 */
export const getSupplierTypes = 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: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getSupplierTypes(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

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

/**
 * Insert supplier contact
 *
 * @mcp
 */
export const insertSupplierContact = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    contact: z.looseObject({
      id: z.string().optional(),
      contactId: z.string().optional(),
      firstName: z.string().optional(),
      lastName: z.string().optional(),
      title: z.string().optional(),
      email: z.string().min(1),
      mobilePhone: z.string().optional(),
      homePhone: z.string().optional(),
      workPhone: z.string().optional(),
      notes: z.string().optional(),
      supplierLocationId: z.string().optional()
    }),
    supplierLocationId: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.insertSupplierContact(
        ctx.asSystem.pg,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Insert supplier location
 *
 * @mcp
 */
export const insertSupplierLocation = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    name: z.string(),
    address: z.looseObject({
      addressLine1: z.string().optional(),
      addressLine2: z.string().optional(),
      city: z.string().optional(),
      stateProvince: z.string().optional(),
      postalCode: z.string().optional(),
      countryCode: z.string().optional()
    }),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.insertSupplierLocation(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Update purchase order exchange rate
 *
 * @mcp
 */
export const updatePurchaseOrderExchangeRate = defineServiceFn({
  input: z.looseObject({ id: z.string(), exchangeRate: z.number() }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updatePurchaseOrderExchangeRate(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Mark or unmark a purchase order as one of the caller's favorites.
 *
 * @remarks
 * Changes only the caller's own favorites list; the record is unchanged.
 *
 * @mcp
 */
export const updatePurchaseOrderFavorite = defineServiceFn({
  input: z.looseObject({ id: z.string(), favorite: z.boolean() }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updatePurchaseOrderFavorite(
        ctx.asCaller.supabase,
        payload(ctx, input).withUser().build() as never
      )
    );
  }
});

/**
 * Update supplier contact
 *
 * @mcp
 */
export const updateSupplierContact = defineServiceFn({
  input: z.looseObject({
    contactId: z.string(),
    contact: z.looseObject({
      id: z.string().optional(),
      contactId: z.string().optional(),
      firstName: z.string().optional(),
      lastName: z.string().optional(),
      title: z.string().optional(),
      email: z.string().min(1),
      mobilePhone: z.string().optional(),
      homePhone: z.string().optional(),
      workPhone: z.string().optional(),
      notes: z.string().optional(),
      supplierLocationId: z.string().optional()
    }),
    supplierLocationId: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierContact(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Update supplier location
 *
 * @mcp
 */
export const updateSupplierLocation = defineServiceFn({
  input: z.looseObject({
    addressId: z.string(),
    name: z.string(),
    address: z.looseObject({
      addressLine1: z.string().optional(),
      addressLine2: z.string().optional(),
      city: z.string().optional(),
      stateProvince: z.string().optional(),
      countryCode: z.string().optional(),
      postalCode: z.string().optional()
    }),
    customFields: z.unknown().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierLocation(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Update supplier payment
 *
 * @mcp
 */
export const updateSupplierPayment = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string().min(1),
    invoiceSupplierId: z.string().optional(),
    invoiceSupplierLocationId: z.string().optional(),
    invoiceSupplierContactId: z.string().optional(),
    paymentTermId: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierPayment(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Update supplier quote exchange rate
 *
 * @mcp
 */
export const updateSupplierQuoteExchangeRate = defineServiceFn({
  input: z.looseObject({ id: z.string(), exchangeRate: z.number() }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierQuoteExchangeRate(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Update supplier quote status
 *
 * @mcp
 */
export const updateSupplierQuoteStatus = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    status: z.enum(["Draft", "Active", "Expired", "Declined", "Cancelled"]),
    assignee: z.null().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierQuoteStatus(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Update supplier shipping
 *
 * @mcp
 */
export const updateSupplierShipping = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string().min(1),
    shippingSupplierId: z.string().optional(),
    shippingSupplierLocationId: z.string().optional(),
    shippingSupplierContactId: z.string().optional(),
    shippingMethodId: z.string().optional(),
    incoterm: z
      .enum([
        "EXW",
        "FCA",
        "FAS",
        "FOB",
        "CPT",
        "CIP",
        "CFR",
        "CIF",
        "DAP",
        "DPU",
        "DDP"
      ])
      .optional(),
    incotermLocation: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierShipping(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

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

/**
 * Update supplier tax
 *
 * @mcp
 */
export const updateSupplierTax = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string().min(1),
    taxId: z.string().optional(),
    vatNumber: z.string().optional(),
    eori: z.string().optional(),
    taxExempt: z.boolean().optional(),
    taxExemptionReason: z
      .enum([
        "Resale",
        "Government",
        "Nonprofit",
        "Agriculture",
        "Industrial",
        "Export",
        "Medical",
        "Educational",
        "Religious",
        "Other"
      ])
      .nullable()
      .optional(),
    taxExemptionCertificateNumber: z.string().optional(),
    taxExemptionCertificatePath: z.string().nullable().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierTax(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a new purchase order with all business logic - generates sequence, creates supplier interaction, resolves payment/shipping defaults from supplier
 *
 * @remarks
 * Create a new purchase order with all business logic - generates sequence, creates supplier interaction, resolves payment/shipping defaults from supplier. LLM can create a PO with just supplierId.
 *
 * @mcp
 */
export const insertPurchaseOrder = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    purchaseOrderId: z.string().optional(),
    purchaseOrderType: z
      .enum(["Purchase", "Return", "Outside Processing"])
      .optional(),
    locationId: z.string().optional(),
    status: z
      .enum([
        "Draft",
        "Planned",
        "Needs Approval",
        "To Review",
        "To Receive",
        "To Receive and Invoice",
        "To Invoice",
        "Completed",
        "Rejected",
        "Closed"
      ])
      .optional(),
    currencyCode: z.string().optional(),
    orderDate: z.string().optional(),
    supplierContactId: z.string().optional(),
    supplierLocationId: z.string().optional(),
    supplierQuoteId: z.string().optional(),
    receiptRequestedDate: z.string().optional(),
    supplierReference: z.string().optional(),
    notes: optionalTiptapDoc,
    externalNotes: optionalTiptapDoc,
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.insertPurchaseOrder(
        ctx.asCaller.supabase,
        payload(ctx, input).withGroup().forUpsert() as never
      )
    );
  }
});

/**
 * Update a purchase order's header.
 *
 * @remarks
 * The supplier, its contact and location, the supplier reference, the type,
 * the order date, the currency (its exchange rate is read again), internal
 * notes and custom fields. Refused on a finalized order. The status changes
 * only through finalize, reopen and close.
 *
 * @mcp
 */
export const updatePurchaseOrder = defineServiceFn({
  input: z.object({
    id: z.string(),
    currencyCode: z.string().optional(),
    orderDate: z.string().optional(),
    supplierId: z.string().optional(),
    supplierContactId: z.string().nullable().optional(),
    supplierLocationId: z.string().nullable().optional(),
    supplierReference: z.string().optional(),
    purchaseOrderType: z.enum(["Purchase", "Outside Processing"]).optional(),
    notes: z.string().nullable().optional(),
    customFields: z.record(z.string(), z.unknown()).optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, { customFields, ...input }) {
    const current = await ctx.asCaller.supabase
      .from("purchaseOrder")
      .select("status")
      .eq("id", input.id)
      .eq("companyId", ctx.company.id)
      .maybeSingle();
    if (current.error) {
      return ctx.error(
        "internal",
        "Failed to read the purchase order",
        current.error
      );
    }
    if (!current.data) return ctx.error("notFound", "Purchase order not found");
    if (isPurchaseOrderLocked(current.data.status)) {
      return ctx.error(
        "rule",
        "Cannot modify a finalized purchase order. To make changes, please cancel this PO and create a new one."
      );
    }
    return unwrap(
      ctx,
      await service.updatePurchaseOrder(ctx.asCaller.supabase, {
        ...input,
        customFields: customFields as Json | undefined,
        updatedBy: ctx.auditUserId
      })
    );
  }
});

/**
 * Upsert purchase order delivery
 *
 * @mcp
 */
export const upsertPurchaseOrderDelivery = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    locationId: z.string().optional(),
    shippingMethodId: z.string().optional(),
    trackingNumber: z.string(),
    deliveryDate: z.string().optional(),
    receiptRequestedDate: z.string().optional(),
    receiptPromisedDate: z.string().optional(),
    dropShipment: z.boolean().optional(),
    customerId: z.string().optional(),
    customerLocationId: z.string().optional(),
    supplierShippingCost: z.number().optional(),
    notes: z.string().optional(),
    incoterm: z
      .enum([
        "EXW",
        "FCA",
        "FAS",
        "FOB",
        "CPT",
        "CIP",
        "CFR",
        "CIF",
        "DAP",
        "DPU",
        "DDP"
      ])
      .optional(),
    incotermLocation: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing", update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchaseOrderDelivery(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a purchase order line
 *
 * @remarks
 * Upsert purchase order line
 *
 * @mcp
 */
export const createPurchaseOrderLine = defineServiceFn({
  input: z.looseObject({
    purchaseOrderId: z.string().min(1),
    purchaseOrderLineType: z.enum([
      "Part",
      "Material",
      "Tool",
      "Consumable",
      "Service",
      "Fixture",
      "G/L Account",
      "Fixed Asset"
    ]),
    itemId: z.string().optional(),
    accountId: z.string().optional(),
    costCenterId: z.string().optional(),
    assetId: z.string().optional(),
    conversionFactor: z.number().optional(),
    description: z.string().optional(),
    exchangeRate: z.number().optional(),
    inventoryUnitOfMeasureCode: z.string().optional(),
    jobId: z.string().optional(),
    jobOperationId: z.string().optional(),
    locationId: z.string().optional(),
    promisedDate: z.string().optional(),
    purchaseQuantity: z.number().optional(),
    purchaseUnitOfMeasureCode: z.string().optional(),
    requiredDate: z.string().optional(),
    storageUnitId: z.string().optional(),
    supplierPartId: z.string().optional(),
    supplierShippingCost: z.number().optional(),
    supplierTaxAmount: z.number().optional(),
    supplierUnitPrice: z.number().optional(),
    taxPercent: z
      .number()
      .min(0)
      .max(1)
      .default(0)
      .describe(
        "Applied when creating; on update a field left out keeps its value."
      ),
    customFields: z.unknown().optional(),
    id: z
      .string()
      .describe("Send to update that record; omit to create a new one.")
      .optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchaseOrderLine(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a purchase order line
 *
 * @remarks
 * Upsert purchase order line
 *
 * @mcp
 */
export const updatePurchaseOrderLine = defineServiceFn({
  input: z
    .looseObject({
      purchaseOrderId: z.string().min(1),
      purchaseOrderLineType: z.enum([
        "Part",
        "Material",
        "Tool",
        "Consumable",
        "Service",
        "Fixture",
        "G/L Account",
        "Fixed Asset"
      ]),
      itemId: z.string().optional(),
      accountId: z.string().optional(),
      costCenterId: z.string().optional(),
      assetId: z.string().optional(),
      conversionFactor: z.number().optional(),
      description: z.string().optional(),
      exchangeRate: z.number().optional(),
      inventoryUnitOfMeasureCode: z.string().optional(),
      jobId: z.string().optional(),
      jobOperationId: z.string().optional(),
      locationId: z.string().optional(),
      promisedDate: z.string().optional(),
      purchaseQuantity: z.number().optional(),
      purchaseUnitOfMeasureCode: z.string().optional(),
      requiredDate: z.string().optional(),
      storageUnitId: z.string().optional(),
      supplierPartId: z.string().optional(),
      supplierShippingCost: z.number().optional(),
      supplierTaxAmount: z.number().optional(),
      supplierUnitPrice: z.number().optional(),
      taxPercent: z
        .number()
        .min(0)
        .max(1)
        .describe(
          "Applied when creating; on update a field left out keeps its value."
        )
        .optional(),
      customFields: z.unknown().optional(),
      id: z
        .string()
        .describe("Send to update that record; omit to create a new one.")
        .optional()
    })
    .required({ id: true }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchaseOrderLine(ctx.asCaller.supabase, {
        ...payload(ctx, input).forUpdate(),
        companyId: ctx.company.id
      } as never)
    );
  }
});

/**
 * Update purchase order line order
 *
 * @mcp
 */
export const updatePurchaseOrderLineOrder = defineServiceFn({
  input: z.looseObject({
    purchaseOrderId: z.string(),
    updates: z.array(z.looseObject({ id: z.string(), sortOrder: z.number() }))
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return await service.updatePurchaseOrderLineOrder(
      ctx.asSystem.pg,
      ctx.company.id,
      ctx.auditUserId,
      input.purchaseOrderId as never,
      payload(ctx, input.updates).forUpdate() as never
    );
  }
});

/**
 * Short-close ("stop receiving") or reopen a purchase order line whose remaining quantity will never arrive
 *
 * @mcp
 */
export const shortClosePurchaseOrderLine = defineServiceFn({
  input: z.looseObject({
    lineId: z.string(),
    purchaseOrderId: z.string(),
    intent: z.enum(["close", "reopen"])
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return await service.shortClosePurchaseOrderLine(
      ctx.asSystem.pg,
      payload(ctx, input).withUser().build() as never
    );
  }
});

/**
 * Upsert purchase order payment
 *
 * @mcp
 */
export const upsertPurchaseOrderPayment = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    invoiceSupplierId: z.string().optional(),
    invoiceSupplierLocationId: z.string().optional(),
    invoiceSupplierContactId: z.string().optional(),
    paymentTermId: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing", update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchaseOrderPayment(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a supplier
 *
 * @remarks
 * Upsert supplier
 *
 * @mcp
 */
export const createSupplier = defineServiceFn({
  input: z.looseObject({
    readableId: z.string().optional(),
    name: z.string().min(1),
    supplierStatus: z
      .enum(["Active", "Inactive", "Pending", "Rejected"])
      .nullable()
      .optional(),
    supplierTypeId: z.string().optional(),
    accountManagerId: z.string().optional(),
    currencyCode: z.string().optional(),
    purchasingContactId: z.string().optional(),
    website: z.string().optional(),
    customFields: z.unknown().optional(),
    id: z
      .string()
      .describe("Send to update that record; omit to create a new one.")
      .optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplier(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a supplier
 *
 * @remarks
 * Upsert supplier
 *
 * @mcp
 */
export const updateSupplier = defineServiceFn({
  input: z
    .looseObject({
      readableId: z.string().optional(),
      name: z.string().min(1),
      supplierStatus: z
        .enum(["Active", "Inactive", "Pending", "Rejected"])
        .nullable()
        .optional(),
      supplierTypeId: z.string().optional(),
      accountManagerId: z.string().optional(),
      currencyCode: z.string().optional(),
      purchasingContactId: z.string().optional(),
      website: z.string().optional(),
      customFields: z.unknown().optional(),
      id: z
        .string()
        .describe("Send to update that record; omit to create a new one.")
        .optional()
    })
    .required({ id: true }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplier(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a supplier process
 *
 * @remarks
 * Upsert supplier process
 *
 * @mcp
 */
export const createSupplierProcess = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string().min(1),
    processId: z.string().min(1),
    minimumCost: z.number().min(0),
    leadTime: z.number().min(0),
    customFields: z.unknown().optional(),
    id: z
      .string()
      .describe("Send to update that record; omit to create a new one.")
      .optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplierProcess(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a supplier process
 *
 * @remarks
 * Upsert supplier process
 *
 * @mcp
 */
export const updateSupplierProcess = defineServiceFn({
  input: z
    .looseObject({
      supplierId: z.string().min(1),
      processId: z.string().min(1),
      minimumCost: z.number().min(0),
      leadTime: z.number().min(0),
      customFields: z.unknown().optional(),
      id: z
        .string()
        .describe("Send to update that record; omit to create a new one.")
        .optional()
    })
    .required({ id: true }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplierProcess(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a new supplier quote with all business logic - generates sequence, creates supplier interaction, sets up external link
 *
 * @remarks
 * Create a new supplier quote with all business logic - generates sequence, creates supplier interaction, sets up external link. LLM can create a quote with just supplierId.
 *
 * @mcp
 */
export const insertSupplierQuote = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    supplierQuoteId: z.string().optional(),
    locationId: z.string().optional(),
    status: z
      .enum(["Draft", "Active", "Expired", "Declined", "Cancelled"])
      .optional(),
    currencyCode: z.string().optional(),
    expirationDate: z.string().optional(),
    supplierContactId: z.string().optional(),
    supplierLocationId: z.string().optional(),
    notes: z.string().optional(),
    customFields: z.unknown().optional(),
    quotedDate: z.string().optional(),
    supplierReference: z.string().optional(),
    supplierQuoteType: z.enum(["Purchase", "Outside Processing"]).optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.insertSupplierQuote(
        ctx.asCaller.supabase,
        payload(ctx, input).withGroup().forUpsert() as never
      )
    );
  }
});

/**
 * Update an existing supplier quote - handles exchange rate updates when currency changes
 *
 * @mcp
 */
export const updateSupplierQuote = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    status: z
      .enum(["Draft", "Active", "Expired", "Declined", "Cancelled"])
      .optional(),
    currencyCode: z.string().optional(),
    expirationDate: z.string().nullable().optional(),
    supplierContactId: z.string().nullable().optional(),
    supplierLocationId: z.string().nullable().optional(),
    notes: z.string().nullable().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateSupplierQuote(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Create a supplier quote line
 *
 * @remarks
 * Upsert supplier quote line
 *
 * @mcp
 */
export const createSupplierQuoteLine = defineServiceFn({
  input: z.looseObject({
    supplierQuoteId: z.string(),
    supplierQuoteLineType: z.enum([
      "Part",
      "Material",
      "Tool",
      "Consumable",
      "Service",
      "G/L Account"
    ]),
    itemId: z.string().optional(),
    accountId: z.string().optional(),
    costCenterId: z.string().optional(),
    description: z.string().optional(),
    supplierPartId: z.string().optional(),
    inventoryUnitOfMeasureCode: z.string().optional(),
    purchaseUnitOfMeasureCode: z.string().optional(),
    conversionFactor: z.number().optional(),
    requiredDate: z.string().optional(),
    quantity: z.array(z.number().min(0.00001)),
    customFields: z.unknown().optional(),
    id: z
      .string()
      .describe("Send to update that record; omit to create a new one.")
      .optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplierQuoteLine(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a supplier quote line
 *
 * @remarks
 * Upsert supplier quote line
 *
 * @mcp
 */
export const updateSupplierQuoteLine = defineServiceFn({
  input: z
    .looseObject({
      supplierQuoteId: z.string(),
      supplierQuoteLineType: z.enum([
        "Part",
        "Material",
        "Tool",
        "Consumable",
        "Service",
        "G/L Account"
      ]),
      itemId: z.string().optional(),
      accountId: z.string().optional(),
      costCenterId: z.string().optional(),
      description: z.string().optional(),
      supplierPartId: z.string().optional(),
      inventoryUnitOfMeasureCode: z.string().optional(),
      purchaseUnitOfMeasureCode: z.string().optional(),
      conversionFactor: z.number().optional(),
      requiredDate: z.string().optional(),
      quantity: z.array(z.number().min(0.00001)),
      customFields: z.unknown().optional(),
      id: z
        .string()
        .describe("Send to update that record; omit to create a new one.")
        .optional()
    })
    .required({ id: true }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplierQuoteLine(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Update supplier quote line order
 *
 * @mcp
 */
export const updateSupplierQuoteLineOrder = defineServiceFn({
  input: z.looseObject({
    supplierQuoteId: z.string(),
    updates: z.array(z.looseObject({ id: z.string(), sortOrder: z.number() }))
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return await service.updateSupplierQuoteLineOrder(
      ctx.asSystem.pg,
      ctx.company.id,
      ctx.auditUserId,
      input.supplierQuoteId as never,
      payload(ctx, input.updates).forUpdate() as never
    );
  }
});

/**
 * Create a supplier type
 *
 * @remarks
 * Upsert supplier type
 *
 * @mcp
 */
export const createSupplierType = defineServiceFn({
  input: z.looseObject({
    name: z.string().min(1),
    customFields: z.unknown().optional(),
    id: z
      .string()
      .describe("Send to update that record; omit to create a new one.")
      .optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplierType(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a supplier type
 *
 * @remarks
 * Upsert supplier type
 *
 * @mcp
 */
export const updateSupplierType = defineServiceFn({
  input: z
    .looseObject({
      name: z.string().min(1),
      customFields: z.unknown().optional(),
      id: z
        .string()
        .describe("Send to update that record; omit to create a new one.")
        .optional()
    })
    .required({ id: true }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertSupplierType(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Delete purchasing r f q
 *
 * @mcp destructive
 */
export const deletePurchasingRFQ = defineServiceFn({
  input: z.looseObject({ purchasingRfqId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deletePurchasingRFQ(
        ctx.asCaller.supabase,
        input.purchasingRfqId as never
      )
    );
  }
});

/**
 * Delete purchasing r f q line
 *
 * @mcp destructive
 */
export const deletePurchasingRFQLine = defineServiceFn({
  input: z.looseObject({ purchasingRfqLineId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deletePurchasingRFQLine(
        ctx.asCaller.supabase,
        input.purchasingRfqLineId as never
      )
    );
  }
});

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

/**
 * Get purchasing r f qs
 *
 * @mcp read
 */
export const getPurchasingRFQs = 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: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getPurchasingRFQs(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Get purchasing r f q line
 *
 * @mcp read
 */
export const getPurchasingRFQLine = defineServiceFn({
  input: z.looseObject({ lineId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchasingRFQLine(
        ctx.asCaller.supabase,
        input.lineId as never
      )
    );
  }
});

/**
 * Get purchasing r f q lines
 *
 * @mcp read
 */
export const getPurchasingRFQLines = defineServiceFn({
  input: z.looseObject({ purchasingRfqId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchasingRFQLines(
        ctx.asCaller.supabase,
        input.purchasingRfqId as never
      )
    );
  }
});

/**
 * Upsert purchasing r f q
 *
 * @mcp
 */
export const upsertPurchasingRFQ = defineServiceFn({
  input: z.looseObject({
    id: z.string().optional(),
    rfqId: z.string(),
    rfqDate: z.string(),
    expirationDate: z.string().optional(),
    locationId: z.string().optional(),
    employeeId: z.string().optional(),
    status: z.enum(["Draft", "Requested", "Closed"]).optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing", update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchasingRFQ(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Create a purchasing rfqline
 *
 * @remarks
 * Upsert purchasing r f q line
 *
 * @mcp
 */
export const createPurchasingRFQLine = defineServiceFn({
  input: z.looseObject({
    purchasingRfqId: z.string(),
    itemId: z.string(),
    description: z.string().optional(),
    quantity: z.array(z.number()),
    purchaseUnitOfMeasureCode: z.string(),
    inventoryUnitOfMeasureCode: z.string(),
    conversionFactor: z.number().optional(),
    order: z.number(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchasingRFQLine(
        ctx.asCaller.supabase,
        payload(ctx, input).forCreate() as never
      )
    );
  }
});

/**
 * Update a purchasing rfqline
 *
 * @remarks
 * Upsert purchasing r f q line
 *
 * @mcp
 */
export const updatePurchasingRFQLine = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    purchasingRfqId: z.string(),
    itemId: z.string(),
    description: z.string().optional(),
    quantity: z.array(z.number()),
    purchaseUnitOfMeasureCode: z.string(),
    inventoryUnitOfMeasureCode: z.string(),
    conversionFactor: z.number().optional(),
    order: z.number(),
    customFields: z.unknown().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchasingRFQLine(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Update purchasing r f q line order
 *
 * @mcp
 */
export const updatePurchasingRFQLineOrder = defineServiceFn({
  input: z.looseObject({
    purchasingRfqId: z.string(),
    updates: z.array(z.looseObject({ id: z.string(), sortOrder: z.number() }))
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return await service.updatePurchasingRFQLineOrder(
      ctx.asSystem.pg,
      ctx.company.id,
      ctx.auditUserId,
      input.purchasingRfqId as never,
      payload(ctx, input.updates).forUpdate() as never
    );
  }
});

/**
 * Upsert purchasing r f q suppliers
 *
 * @mcp destructive
 */
export const upsertPurchasingRFQSuppliers = defineServiceFn({
  input: z.looseObject({
    purchasingRfqId: z.string(),
    supplierIds: z.array(z.string())
  }),
  permission: { create: "purchasing", update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertPurchasingRFQSuppliers(
        ctx.asCaller.supabase,
        input.purchasingRfqId as never,
        payload(ctx, input.supplierIds).forUpsert() as never,
        ctx.company.id,
        ctx.auditUserId
      )
    );
  }
});

/**
 * Update purchasing r f q status
 *
 * @mcp
 */
export const updatePurchasingRFQStatus = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    status: z.enum(["Draft", "Requested", "Closed"]),
    assignee: z.string().nullable().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updatePurchasingRFQStatus(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Get linked supplier quotes
 *
 * @mcp read
 */
export const getLinkedSupplierQuotes = defineServiceFn({
  input: z.looseObject({ purchasingRfqId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getLinkedSupplierQuotes(
        ctx.asCaller.supabase,
        input.purchasingRfqId as never
      )
    );
  }
});

/**
 * Get sibling quotes for quote
 *
 * @mcp read
 */
export const getSiblingQuotesForQuote = defineServiceFn({
  input: z.looseObject({ supplierQuoteId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSiblingQuotesForQuote(
        ctx.asCaller.supabase,
        input.supplierQuoteId as never
      )
    );
  }
});

/**
 * Get supplier quotes for comparison
 *
 * @mcp read
 */
export const getSupplierQuotesForComparison = defineServiceFn({
  input: z.looseObject({ purchasingRfqId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getSupplierQuotesForComparison(
        ctx.asCaller.supabase,
        input.purchasingRfqId as never
      )
    );
  }
});

/**
 * Get purchasing r f q suppliers with links
 *
 * @mcp read
 */
export const getPurchasingRFQSuppliersWithLinks = defineServiceFn({
  input: z.looseObject({ purchasingRfqId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchasingRFQSuppliersWithLinks(
        ctx.asCaller.supabase,
        input.purchasingRfqId as never
      )
    );
  }
});

/**
 * Get default attachments for p o
 *
 * @mcp read
 */
export const getDefaultAttachmentsForPO = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string().nullable(),
    itemIds: z.array(z.string())
  }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return await service.getDefaultAttachmentsForPO(
      ctx.asCaller.supabase,
      payload(ctx, input).build() as never
    );
  }
});

/**
 * Get purchase return orders
 *
 * @mcp read
 */
export const getPurchaseReturnOrders = 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(),
    status: z.string().nullable().optional(),
    supplierId: z.string().nullable().optional()
  }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getPurchaseReturnOrders(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

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

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

/**
 * Get purchase return order line
 *
 * @mcp read
 */
export const getPurchaseReturnOrderLine = defineServiceFn({
  input: z.looseObject({ lineId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchaseReturnOrderLine(
        ctx.asCaller.supabase,
        input.lineId as never
      )
    );
  }
});

/**
 * Get purchase return order line tracked entities
 *
 * @mcp read
 */
export const getPurchaseReturnOrderLineTrackedEntities = defineServiceFn({
  input: z.looseObject({ lineIds: z.array(z.string()) }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getPurchaseReturnOrderLineTrackedEntities(
        ctx.asCaller.supabase,
        payload(ctx, input.lineIds).build() as never
      )
    );
  }
});

/**
 * Insert purchase return order
 *
 * @mcp
 */
export const insertPurchaseReturnOrder = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    purchaseReturnOrderId: z.string().optional(),
    orderDate: z.string(),
    supplierLocationId: z.string().optional(),
    supplierContactId: z.string().optional(),
    supplierReference: z.string().optional(),
    locationId: z.string().optional(),
    purchaseOrderId: z.string().optional(),
    currencyCode: z.string().optional(),
    expirationDate: z.string().optional(),
    assignee: z.string().optional(),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.insertPurchaseReturnOrder(
        ctx.asCaller.supabase,
        payload(ctx, input).withGroup().forUpsert() as never
      )
    );
  }
});

/**
 * Delete purchase return order
 *
 * @mcp destructive
 */
export const deletePurchaseReturnOrder = defineServiceFn({
  input: z.looseObject({ purchaseReturnOrderId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deletePurchaseReturnOrder(
        ctx.asCaller.supabase,
        input.purchaseReturnOrderId as never
      )
    );
  }
});

/**
 * Delete purchase return order line
 *
 * @mcp destructive
 */
export const deletePurchaseReturnOrderLine = defineServiceFn({
  input: z.looseObject({ lineId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deletePurchaseReturnOrderLine(
        ctx.asCaller.supabase,
        input.lineId as never
      )
    );
  }
});

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

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

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

/**
 * Short-close ("stop expecting") a supplier return line — the shortClosePurchaseOrderLine mechanic
 *
 * @mcp
 */
export const shortClosePurchaseReturnOrderLine = defineServiceFn({
  input: z.looseObject({
    lineId: z.string(),
    purchaseReturnOrderId: z.string(),
    intent: z.enum(["close", "reopen"])
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return await service.shortClosePurchaseReturnOrderLine(
      ctx.asSystem.pg,
      payload(ctx, input).withUser().build() as never
    );
  }
});

/**
 * Returnable receipt lines for a supplier, searched + paginated in the database via the get_returnable_receipt_lines RPC
 *
 * @mcp read
 */
export const getReturnableLinesForSupplier = defineServiceFn({
  input: z.looseObject({
    supplierId: z.string(),
    purchaseOrderId: z.string().optional(),
    search: z.string().optional(),
    limit: z.number().optional(),
    offset: z.number().optional()
  }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getReturnableLinesForSupplier(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.supplierId as never,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Entity picker source for supplier return lines: serials/batches on hand that were received from this supplier
 *
 * @mcp read
 */
export const getReturnableEntitiesForSupplier = defineServiceFn({
  input: z.looseObject({ supplierId: z.string(), itemId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getReturnableEntitiesForSupplier(
        ctx.asCaller.supabase,
        ctx.company.id,
        input.supplierId as never,
        input.itemId as never
      )
    );
  }
});

/**
 * Per-line creditable pool = shipped − already credited
 *
 * @mcp read
 */
export const getCreditableQuantitiesForPurchaseReturn = defineServiceFn({
  input: z.looseObject({ purchaseReturnOrderId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getCreditableQuantitiesForPurchaseReturn(
        ctx.asCaller.supabase,
        input.purchaseReturnOrderId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Issue supplier credit: one AP memo + per-line purchaseReturnOrderCreditLine breakdown
 *
 * @mcp
 */
export const createPurchaseReturnOrderCredit = defineServiceFn({
  input: z.looseObject({
    purchaseReturnOrderId: z.string(),
    memoDate: z.string(),
    lines: z.array(
      z.looseObject({
        purchaseReturnOrderLineId: z.string(),
        quantity: z.number()
      })
    )
  }),
  permission: { create: "invoicing" },
  async run(ctx, input) {
    return await service.createPurchaseReturnOrderCredit(
      ctx.asCaller.supabase,
      ctx.asSystem.pg,
      payload(ctx, input).withGroup().withUser().forUpsert() as never
    );
  }
});

/**
 * Create a replacement purchase order from a supplier return: a Draft order of
 * the return lines, priced from the linked order line, else the supplier part.
 *
 * @remarks
 * One replacement per return.
 *
 * @mcp
 */
export const createReplacementPurchaseOrder = defineServiceFn({
  input: z.looseObject({ purchaseReturnOrderId: z.string() }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.createReplacementPurchaseOrder(
        ctx.asCaller.supabase,
        payload(ctx, input).withGroup().withUser().forUpsert() as never
      )
    );
  }
});

/**
 * Create a presigned upload URL for a supplier interaction (purchase order/supplier quote/RFQ) document
 *
 * @mcp
 */
export const createSupplierInteractionDocumentUploadUrl = defineServiceFn({
  input: z.looseObject({ interactionId: z.string(), name: z.string() }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.createSupplierInteractionDocumentUploadUrl(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Create a presigned upload URL for a supplier interaction LINE document
 *
 * @mcp
 */
export const createSupplierInteractionLineDocumentUploadUrl = defineServiceFn({
  input: z.looseObject({ lineId: z.string(), name: z.string() }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.createSupplierInteractionLineDocumentUploadUrl(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Get leases
 *
 * @mcp read
 */
export const getLeases = 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: "purchasing" },
  async run(ctx, input) {
    return paged(
      ctx,
      await service.getLeases(
        ctx.asCaller.supabase,
        ctx.company.id,
        payload(ctx, input).build() as never
      )
    );
  }
});

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

/**
 * Create a lease.
 *
 * @remarks
 * The caller supplies `leaseId`, the readable LSE number. The app draws it from
 * the sequence.
 *
 * @mcp
 */
export const insertLease = defineServiceFn({
  input: z.looseObject({
    leaseId: z.string(),
    name: z.string().optional(),
    description: z.string().optional(),
    supplierId: z.string().min(1),
    supplierLocationId: z.string().optional(),
    supplierContactId: z.string().optional(),
    locationId: z.string().optional(),
    assignee: z.string().optional(),
    commencementDate: z.string().min(1),
    duration: z
      .enum(["12", "24", "36", "48", "60", "open", "custom"])
      .optional(),
    endDate: z.string().optional(),
    noticeDate: z.string().optional(),
    invoiceFromDate: z.string().optional(),
    paymentFrequency: z.enum(["Monthly", "Quarterly", "Annual"]),
    paymentTiming: z.enum(["Advance", "Arrears"]),
    annualEscalationPercent: z.number().min(0).default(0),
    discountRate: z.number().min(0),
    currencyCode: z.string().min(1),
    customFields: z.unknown().optional()
  }),
  permission: { create: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.insertLease(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpsert() as never
      )
    );
  }
});

/**
 * Update a lease's details.
 *
 * @remarks
 * The details are its name, notes, owner and notice date (`leaseDetailFields`).
 * They stay editable in every status, because nothing is measured from them.
 *
 * @mcp
 */
export const updateLeaseDetails = defineServiceFn({
  input: z.looseObject({
    id: z.string(),
    name: z.string().nullable().optional(),
    description: z.string().nullable().optional(),
    assignee: z.string().nullable().optional(),
    noticeDate: z.string().nullable().optional()
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.updateLeaseDetails(
        ctx.asCaller.supabase,
        payload(ctx, input).forUpdate() as never
      )
    );
  }
});

/**
 * Only a Draft lease can be deleted; cancel an active one
 *
 * @mcp destructive
 */
export const deleteLease = defineServiceFn({
  input: z.looseObject({ leaseId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteLease(
        ctx.asCaller.supabase,
        input.leaseId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * The lease's assets in their order
 *
 * @mcp read
 */
export const getLeaseLines = defineServiceFn({
  input: z.looseObject({ leaseId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getLeaseLines(
        ctx.asCaller.supabase,
        input.leaseId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Every payment row of every asset: a long lease of many assets runs past PostgREST's 1,000-row page
 *
 * @mcp read
 */
export const getLeasePayments = defineServiceFn({
  input: z.looseObject({ leaseId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getLeasePayments(
        ctx.asCaller.supabase,
        input.leaseId as never,
        ctx.company.id
      )
    );
  }
});

/**
 * Removes an asset, and its payment rows with it, from a Draft lease
 *
 * @mcp destructive
 */
export const deleteLeaseLine = defineServiceFn({
  input: z.looseObject({ leaseId: z.string(), leaseLineId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteLeaseLine(
        ctx.asCaller.supabase,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * Add or change one payment row of a Draft lease's asset (a rent holiday, an irregular step)
 *
 * @mcp
 */
export const upsertLeasePayment = defineServiceFn({
  input: z.looseObject({
    id: z.string().optional(),
    leaseId: z.string().min(1),
    leaseLineId: z.string().min(1),
    paymentType: z
      .enum(["Rent", "Purchase Option", "Termination Penalty"])
      .optional(),
    periodStart: z.string().min(1),
    periodEnd: z.string().min(1),
    dueDate: z.string().min(1),
    amount: z.number().min(0)
  }),
  permission: { update: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.upsertLeasePayment(
        ctx.asCaller.supabase,
        payload(ctx, input).withUser().forUpdate() as never
      )
    );
  }
});

/**
 * Delete lease payment
 *
 * @mcp destructive
 */
export const deleteLeasePayment = defineServiceFn({
  input: z.looseObject({ leaseId: z.string(), paymentId: z.string() }),
  permission: { delete: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.deleteLeasePayment(
        ctx.asCaller.supabase,
        payload(ctx, input).build() as never
      )
    );
  }
});

/**
 * The monthly schedule of every asset, each line with whether its lease run rows have posted: a long lease of many assets runs past PostgREST's 1,000-row page
 *
 * @mcp read
 */
export const getLeaseSchedule = defineServiceFn({
  input: z.looseObject({ leaseId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getLeaseSchedule(
        ctx.asCaller.supabase,
        input.leaseId as never,
        ctx.company.id
      )
    );
  }
});

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

/**
 * The purchase invoices that bill the lease, and the journals that name it
 *
 * @mcp read
 */
export const getLeaseRelatedDocuments = defineServiceFn({
  input: z.looseObject({ leaseId: z.string() }),
  permission: { view: "purchasing" },
  async run(ctx, input) {
    return unwrap(
      ctx,
      await service.getLeaseRelatedDocuments(
        ctx.asCaller.supabase,
        input.leaseId as never,
        ctx.company.id
      )
    );
  }
});