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.

52.6 KB
Raw Blame
// SPDX-License-Identifier: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.

import { Constants, type Database } from "@carbon/database";
import z from "zod";
import type {
  AccountingEntity,
  AccountingEntityType,
  EntityDefinition,
  GlobalSyncConfig
} from "./types";

function withNullable<T extends z.ZodTypeAny>(schema: T) {
  return z.preprocess((v) => (v === undefined ? null : v), schema.nullish());
}

export enum ProviderID {
  XERO = "xero",
  QUICKBOOKS = "quickbooks",
  RILLET = "rillet"
  // SAGE = "sage",
}

/**
 * Spend-management platforms. A separate enum from `ProviderID` rather than a
 * member of it: the two roles answer different questions, and every existing
 * `ProviderID` consumer means "an accounting provider" — widening that enum
 * would silently make each of them wrong.
 */
export enum SpendProviderID {
  RAMP = "ramp"
}

/**
 * Any provider the sync engine can dispatch for. `SyncFactory` is keyed on
 * this; almost everything else should keep naming the role it actually means.
 */
export type SyncProviderID = ProviderID | SpendProviderID;

/**
 * Schemas for shared provider entities and credentials.
 */

export const ProviderCredentialsSchema = z.discriminatedUnion("type", [
  z.object({
    type: z.literal("oauth2"),
    accessToken: z.string(),
    refreshToken: z.string().optional(),
    expiresAt: z.string().datetime().optional(),
    scope: z.array(z.string()).optional(),
    providerMetadata: z.record(z.string(), z.unknown()).optional() // xero: { tenantId, tenantName }; qbo: { realmId }
  }),
  z.object({
    type: z.literal("apiKey"),
    apiKey: z.string().min(1),
    /** Which host the key belongs to — API keys are environment-specific. */
    environment: z.enum(["production", "sandbox"]).default("production"),
    // rillet: { subsidiaryId?, webhookToken? }
    providerMetadata: z.record(z.string(), z.unknown()).optional()
  }),
  z.object({
    type: z.literal("bridge"),
    vendor: z.string(), // e.g. "conductor"
    externalConnectionId: z.string() // e.g. Conductor end-user id
  })
]);

/**
 * Legacy stored oauth2 credentials kept provider-specific fields
 * (`tenantId`/`tenantName`) at the top level. Fold them into
 * `providerMetadata` before parsing — zod strips unknown keys, so parsing
 * the flat shape directly against the union would silently drop the tenant.
 */
function normalizeStoredCredentials(raw: unknown): unknown {
  if (
    typeof raw !== "object" ||
    raw === null ||
    (raw as Record<string, unknown>).type !== "oauth2" ||
    (!("tenantId" in raw) && !("tenantName" in raw))
  ) {
    return raw;
  }

  const { tenantId, tenantName, providerMetadata, ...rest } = raw as Record<
    string,
    unknown
  >;

  return {
    ...rest,
    providerMetadata: {
      ...(tenantId !== undefined ? { tenantId } : {}),
      ...(tenantName !== undefined ? { tenantName } : {}),
      ...(typeof providerMetadata === "object" && providerMetadata !== null
        ? providerMetadata
        : {})
    }
  };
}

/**
 * Credentials as they are stored on `companyIntegration.metadata` — reads the
 * new discriminated union, transparently upgrading the legacy flat oauth2
 * shape. Writes always use the new shape.
 */
export const StoredProviderCredentialsSchema = z.preprocess(
  normalizeStoredCredentials,
  ProviderCredentialsSchema
);

/**
 * Parse credentials read from storage. Accepts the new union and the legacy
 * flat oauth2 shape (mapped into `providerMetadata`). Throws if neither
 * parses.
 */
export function parseStoredCredentials(
  raw: unknown
): z.output<typeof ProviderCredentialsSchema> {
  return StoredProviderCredentialsSchema.parse(raw);
}

/**
 * Direction of data flow.
 */
export const SyncDirectionSchema = z.enum([
  "two-way",
  "push-to-accounting",
  "pull-from-accounting"
]);

export const AccountingSyncSchema = z.object({
  companyId: z.string(),
  provider: z.nativeEnum(ProviderID),
  syncType: z.enum(["webhook", "scheduled", "trigger"]),
  syncDirection: SyncDirectionSchema,
  entities: z.array(z.custom<AccountingEntity>()),
  metadata: z.record(z.string(), z.any()).optional()
});

export const ENTITY_DEFINITIONS: Record<
  AccountingEntityType,
  EntityDefinition
> = {
  customer: {
    label: "Customers",
    type: "master",
    supportedDirections: [
      "two-way",
      "push-to-accounting",
      "pull-from-accounting"
    ]
  },
  vendor: {
    label: "Suppliers",
    type: "master",
    supportedDirections: [
      "two-way",
      "push-to-accounting",
      "pull-from-accounting"
    ]
  },
  item: {
    label: "Items / Products",
    type: "master",
    supportedDirections: ["two-way", "push-to-accounting"]
  },
  employee: {
    label: "Employees",
    type: "master",
    supportedDirections: ["two-way", "push-to-accounting"]
  },
  purchaseOrder: {
    label: "Purchase Orders",
    type: "transaction",
    dependsOn: ["vendor", "item"],
    supportedDirections: ["push-to-accounting"]
  },
  bill: {
    label: "Bills (Purchase Invoices)",
    type: "transaction",
    // NOT `item`. A bill is an account-costed replay of its posting journal —
    // the item is a line label, never a GL driver — so no bill syncer references
    // an item on the push: Xero passes `nonTrackedItemIds: undefined` (an
    // `ItemCode` for a tracked item would double-post inventory), QBO and Rillet
    // build account-coded lines, and none of the three calls
    // `ensureDependencySynced("item", …)`. The `ItemRef`/`ItemCode` reads in
    // those files are on the PULL path, mapping an inbound provider bill back to
    // Carbon.
    //
    // This is load-bearing, not cosmetic: `validateSyncConfig` refuses to enable
    // an entity while a declared dependency is disabled, so the stale `item` here
    // made "bills on, items off" an invalid config — blocking the one thing a
    // customer would most reasonably want. Purchase/sales ORDERS and sales
    // INVOICES keep the dependency: they genuinely reference items (see
    // `.ai/specs/implemented/2026-08-05-accounting-document-representation.md`
    // — AP replays the journal, AR is item-referenced to the item's revenue
    // account, and non-posting documents carry item detail as pure benefit).
    dependsOn: ["vendor"],
    supportedDirections: ["two-way", "push-to-accounting"]
  },
  salesOrder: {
    label: "Sales Orders",
    type: "transaction",
    dependsOn: ["customer", "item"],
    supportedDirections: ["push-to-accounting"]
  },
  invoice: {
    label: "Sales Invoices",
    type: "transaction",
    // NOT `item` — AR invoice lines no longer reference Carbon items. Each line
    // carries a SYNTHETIC per-revenue-account item (Rillet product / QBO item)
    // or none at all (Xero, whose lines are account-coded), replaying the
    // account the ORIGINAL journal credited.
    //
    // The 2026-08-05 spec justified item-referenced AR on "the item's revenue
    // account IS what the invoice should post". That premise no longer holds:
    // Carbon has no per-item revenue account — `post-sales-invoice` credits
    // `accountDefault.salesAccount` for ALL merchandise and
    // `salesShippingRevenueAccount` for shipping — so the item reference bought
    // subledger detail only, at the cost of mirroring a manufacturing parts
    // catalog into the provider. The posted GL is byte-identical without it.
    dependsOn: ["customer"],
    supportedDirections: ["two-way", "push-to-accounting"]
  },
  payment: {
    label: "Payments",
    type: "transaction",
    dependsOn: ["invoice", "bill"],
    // Two-way: provider-recorded payments pull back (Phase F), and Carbon-born
    // Posted payments push out as provider payment documents (Phase G). Routing
    // is per-record by origin (the payment mapping), not a static direction.
    supportedDirections: [
      "two-way",
      "pull-from-accounting",
      "push-to-accounting"
    ]
  },
  inventoryAdjustment: {
    label: "Inventory Adjustments",
    type: "transaction",
    dependsOn: ["item"],
    supportedDirections: ["push-to-accounting"]
  },
  journalEntry: {
    label: "Journal Entries",
    type: "transaction",
    supportedDirections: ["push-to-accounting"]
  },
  charge: {
    label: "Card Charges",
    type: "transaction",
    dependsOn: ["vendor"],
    supportedDirections: ["push-to-accounting"]
  },
  creditMemo: {
    label: "Credit Memos",
    type: "transaction",
    dependsOn: ["customer", "invoice"],
    supportedDirections: ["push-to-accounting"]
  },
  supplierCredit: {
    label: "Supplier Credits",
    type: "transaction",
    dependsOn: ["vendor", "bill"],
    supportedDirections: ["push-to-accounting"]
  },
  reimbursement: {
    label: "Reimbursements",
    type: "transaction",
    // The payee is a Carbon `employee`, but every provider represents it with
    // a VENDOR-side counterparty (Rillet `vendor_id`, QBO Vendor, Xero
    // Contact), so the vendor master must exist before the document.
    dependsOn: ["vendor"],
    supportedDirections: ["push-to-accounting"]
  }
};

/**
 * Default Safe Configuration
 */
export const DEFAULT_SYNC_CONFIG: GlobalSyncConfig = {
  entities: {
    customer: {
      enabled: true,
      direction: "two-way",
      owner: "accounting"
    },
    vendor: { enabled: true, direction: "two-way", owner: "accounting" },
    item: { enabled: true, direction: "push-to-accounting", owner: "carbon" },
    employee: {
      enabled: false, // https://developer.xero.com/documentation/api/accounting/employees
      direction: "two-way",
      owner: "carbon"
    },
    purchaseOrder: {
      enabled: true,
      direction: "push-to-accounting",
      owner: "carbon"
    },
    bill: { enabled: true, direction: "two-way", owner: "accounting" },
    salesOrder: {
      enabled: false,
      direction: "push-to-accounting",
      owner: "carbon"
    },
    invoice: { enabled: true, direction: "two-way", owner: "accounting" },
    payment: {
      enabled: false,
      direction: "pull-from-accounting",
      owner: "accounting"
    },
    inventoryAdjustment: {
      enabled: false,
      direction: "push-to-accounting",
      owner: "carbon"
    },
    journalEntry: {
      // Always-on: automated postings ARE the sync (the always-on model) —
      // connecting an accounting integration means Carbon's automated GL
      // postings mirror to it. Manual journals are excluded by POSTING_POLICY
      // (syncable: false), not by this flag.
      enabled: true,
      direction: "push-to-accounting",
      owner: "carbon"
    },
    charge: {
      // Card charges (Charge/Credit charges) push as the provider's
      // native card-charge object; while enabled, their "Charge"
      // journals are DOC_BACKED-excluded per row (core/posting.ts) so the
      // same spend is never both a journal entry and a charge.
      enabled: true,
      direction: "push-to-accounting",
      owner: "carbon"
    },
    // Memo credits are opt-in (families default to "none"); see
    // PostingSyncStoredSchema.families.
    creditMemo: {
      enabled: false,
      direction: "push-to-accounting",
      owner: "carbon"
    },
    supplierCredit: {
      enabled: false,
      direction: "push-to-accounting",
      owner: "carbon"
    },
    // Employee reimbursements are opt-in: an upgrading integration must not
    // start pushing a new AP document to the customer's ledger unasked. Spec
    // `.ai/specs/implemented/2026-09-23-reimbursements-first-class.md`: defaultEnabled false.
    reimbursement: {
      enabled: false,
      direction: "push-to-accounting",
      owner: "carbon"
    }
  }
};

// /********************************************************\
// *              Posting Sync (journalEntry)               *
// \********************************************************/

export type JournalEntrySourceType =
  Database["public"]["Enums"]["journalEntrySourceType"];

/** How a source type CAN be represented in the provider (structural). */
export type JournalRepresentation = "journal" | "document";

export type PostingGranularity = "individual" | "daily-summary";

/**
 * Which per-company family setting decides a document-represented type:
 * AR (invoice-side), AP (bill-side), or resolved per journal from its
 * control-account lines (Payment spans both sides).
 */
export type PostingSourceFamily =
  | "ar"
  | "ap"
  | "per-line"
  /**
   * Resolved per journal from the MEMO'S PARTY, not its direction: a customer
   * memo is gated by `creditMemo`, a supplier memo by `supplierCredit`, in both
   * directions. Direction alone would misfile the two "crossing" combos
   * (supplier+Credit, customer+Debit).
   */
  | "per-party";

export type PostingPolicyEntry = {
  representation: JournalRepresentation;
  /** Only document-represented types carry a family. */
  family?: PostingSourceFamily;
  /**
   * For document-represented types: the entity whose DOCUMENT sync carries
   * the journal's amounts into the provider ("invoice" | "bill" | "payment"),
   * or null when no document representation exists yet (memos/returns) —
   * those park loudly in documents mode instead of excluding silently.
   */
  backingEntityType?:
    | "invoice"
    | "bill"
    | "payment"
    | "creditMemo"
    | "supplierCredit"
    | "reimbursement"
    /** Resolved from the memo's party at decision time. */
    | "per-party"
    | null;
  /**
   * `false` ONLY for `Manual` — manual journals are NEVER synced in any engine.
   * They can touch arbitrary/unmapped accounts, and the external ledger owns
   * manual journals (payroll, etc.); Carbon syncs only its automated postings.
   * Omitted ⇒ syncable (every automated posting type).
   */
  syncable?: boolean;
  defaultEnabled: boolean;
  defaultGranularity: PostingGranularity;
};

/**
 * The total posting policy: EVERY "journalEntrySourceType" enum value has a
 * row (Record<> makes omission a compile error — adding an enum value
 * without deciding its policy breaks typecheck, not production).
 * Spec: .ai/specs/2026-08-02-accounting-sync-engine-v3.md §2.
 */
export const POSTING_POLICY: Record<
  JournalEntrySourceType,
  PostingPolicyEntry
> = {
  Manual: {
    representation: "journal",
    syncable: false,
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  // Opening balances are a one-time setup artifact that touches arbitrary
  // accounts; the external ledger owns its own opening balances (connecting a
  // provider brings theirs), so Carbon's opening-balance journal NEVER syncs —
  // same policy as Manual, to avoid double-counting.
  "Opening Balance": {
    representation: "journal",
    syncable: false,
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Purchase Receipt": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  // New in the returns module. Left OFF by default so upgrading an existing
  // integration never starts pushing a new journal type to the customer's
  // ledger unasked — this keeps POSTING_SYNC_DEFAULT_SOURCE_TYPES at the
  // frozen v2 set. Flip to true if returns should sync out of the box.
  "Purchase Return Shipment": {
    representation: "journal",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Transfer Receipt": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Sales Shipment": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  // New in the returns module. Left OFF by default so upgrading an existing
  // integration never starts pushing a new journal type to the customer's
  // ledger unasked — this keeps POSTING_SYNC_DEFAULT_SOURCE_TYPES at the
  // frozen v2 set. Flip to true if returns should sync out of the box.
  "Sales Return Receipt": {
    representation: "journal",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  // New in the returns module (return-to-customer shipments; these used to
  // post as "Sales Shipment", which pushed them through the always-on policy
  // and double-counted them in shipment reporting). Same opt-in stance as the
  // other two return types.
  "Sales Return Shipment": {
    representation: "journal",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Inventory Adjustment": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  Charge: {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Production Order": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Production Event": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Job Consumption": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Job Receipt": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Job Close": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  // Maintenance labor, like production time, posts often and in small amounts.
  "Maintenance Event": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Asset Depreciation": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Asset Disposal": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  // Off by default like the returns types above: a new journal type must never
  // start pushing to a customer's external ledger unasked (plan decision 1,
  // `.ai/plans/implemented/2026-09-22-revenue-recognition-rentals-and-contracts.md` Part I).
  "Revenue Recognition": {
    representation: "journal",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  // Inventory ↔ fixed-asset transfers and job completions to an asset. Off by
  // default for the same reason as 'Revenue Recognition'.
  "Asset Transfer": {
    representation: "journal",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  // One-off lease journals: a sales-type lease's commencement and end of
  // term, and a lessee lease's commencement or opening balance, modification,
  // termination, purchase and cancel. Off by default for the same reason as
  // 'Revenue Recognition'.
  Lease: {
    representation: "journal",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  // Lease runs (lessee interest and amortization, rental deferrals, accruals
  // and sales-type interest). Off by default, as 'Revenue Recognition'.
  "Lease Run": {
    representation: "journal",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Non-Conformance": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Inbound Inspection": {
    representation: "journal",
    defaultEnabled: true,
    defaultGranularity: "individual"
  },
  "Sales Invoice": {
    representation: "document",
    family: "ar",
    backingEntityType: "invoice",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Credit Memo": {
    representation: "document",
    // Party-resolved, NOT direction-resolved — a supplier memo in the Credit
    // direction is a supplier credit, not an AR document.
    family: "per-party",
    backingEntityType: "per-party",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Sales Return": {
    representation: "document",
    family: "ar",
    backingEntityType: null,
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Purchase Invoice": {
    representation: "document",
    family: "ap",
    backingEntityType: "bill",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Debit Memo": {
    representation: "document",
    // Party-resolved — see "Credit Memo".
    family: "per-party",
    backingEntityType: "per-party",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  /**
   * Employee reimbursement — backed by the `reimbursement` entity sync
   * (Rillet native `/reimbursements`; an employee-vendor Bill on QBO and an
   * employee-Contact ACCPAY invoice on Xero). The journal itself is
   * DOC_BACKED-excluded whenever that entity is enabled, so a reimbursement
   * reaches the provider as exactly one of the two, never both.
   */
  Reimbursement: {
    representation: "document",
    family: "ap",
    backingEntityType: "reimbursement",
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  "Purchase Return": {
    representation: "document",
    family: "ap",
    backingEntityType: null,
    defaultEnabled: false,
    defaultGranularity: "individual"
  },
  Payment: {
    representation: "document",
    family: "per-line",
    backingEntityType: "payment",
    defaultEnabled: false,
    defaultGranularity: "individual"
  }
};

export const JOURNAL_ENTRY_SOURCE_TYPES = Object.keys(
  POSTING_POLICY
) as JournalEntrySourceType[];

/**
 * Machine reasons recorded on terminal `Excluded` operations — the policy
 * decided a posted journal is not pushed as a journal, and why.
 */
export const POSTING_DECISION_REASON_CODES = [
  "DOC_BACKED",
  "FAMILY_OFF",
  "SOURCE_TYPE_DISABLED",
  "MANUAL_DISABLED"
] as const;

export type PostingDecisionReasonCode =
  (typeof POSTING_DECISION_REASON_CODES)[number];

/**
 * @deprecated Derived from POSTING_POLICY (journal-represented types enabled
 * by default). Read the policy directly for new code.
 */
export const POSTING_SYNC_DEFAULT_SOURCE_TYPES =
  JOURNAL_ENTRY_SOURCE_TYPES.filter(
    (sourceType) =>
      POSTING_POLICY[sourceType].representation === "journal" &&
      POSTING_POLICY[sourceType].defaultEnabled
  );

/**
 * @deprecated Derived from POSTING_POLICY (document-represented types).
 * Whether a document-represented journal is DOC_BACKED, parked, or pushed
 * now depends on the company's family representation setting — read the
 * policy + settings through getJournalPostingPolicyDecision instead.
 */
export const POSTING_SYNC_EXCLUDED_SOURCE_TYPES =
  JOURNAL_ENTRY_SOURCE_TYPES.filter(
    (sourceType) => POSTING_POLICY[sourceType].representation === "document"
  );

/**
 * Why a balance-INCREASING memo (supplier+Credit, customer+Debit) is skipped.
 *
 * Canonical here because all three providers skip for the identical reason and
 * `accounting/index.ts` star-exports both `core/*` and `providers/*` into one
 * namespace — three independently-declared copies collided at typecheck.
 */
export const MEMO_INCREASER_SKIP_REASON =
  "Balance-increasing memos are not supported in v1";

export const PostingSyncFamilyModeSchema = z.enum([
  "documents",
  "journals",
  "none"
]);

export type PostingSyncFamilyMode = z.infer<typeof PostingSyncFamilyModeSchema>;

export const PostingSyncGranularitySchema = z.enum([
  "individual",
  "daily-summary"
]);

export const PostingSyncDimensionSlotSchema = z.object({
  dimensionId: z.string(),
  /** Provider-specific target id (e.g. "class", "tracking:<id>", "field:<id>"). */
  target: z.string(),
  /**
   * Create missing provider options by name at push time. Optional so a
   * stored slot without the flag resolves to the PROVIDER default at the
   * point of use (Rillet: on — Field-value upsert is the expected flow;
   * QBO/Xero: off — opt-in avoids surprise writes to their lists). See
   * resolveDimensionSlotAutoCreate (core/dimension-mapping.ts).
   */
  autoCreate: z.boolean().optional()
});

export type PostingSyncDimensionSlot = z.infer<
  typeof PostingSyncDimensionSlotSchema
>;

const PostingSyncSourceTypeConfigSchema = z.object({
  enabled: z.boolean(),
  granularity: PostingSyncGranularitySchema
});

/**
 * Upgrade a stored v2 posting-sync fragment (flat `sourceTypes: string[]`,
 * global `consolidation`, `includeManual`) to the v3 per-source-type shape,
 * and carry the pre-rename `families.vendorCredit` key onto
 * `families.supplierCredit`.
 *
 * Behavior parity: the v2 enabled set carries over exactly, the global
 * consolidation becomes every type's granularity, and `includeManual` maps
 * to `sourceTypes.Manual.enabled`. v3 fragments pass through untouched.
 * Write-back in the new shape happens on the next settings save.
 */
function normalizeStoredPostingSyncSettings(raw: unknown): unknown {
  if (typeof raw !== "object" || raw === null) return raw;
  let record = raw as Record<string, unknown>;

  // `vendorCredit` → `supplierCredit` (Carbon says supplier; only the
  // providers say vendor). The migration rewrites every stored row, so this
  // only has to catch one written by an instance still running the old code
  // during the deploy window. It matters because the key DEFAULTS to "none":
  // a dropped value does not fail, it silently stops pushing supplier credits
  // for a company that had turned them on.
  const families = record.families;
  if (
    typeof families === "object" &&
    families !== null &&
    "vendorCredit" in families
  ) {
    const { vendorCredit, ...rest } = families as Record<string, unknown>;
    record = {
      ...record,
      families: {
        ...rest,
        // A value already under the new key wins — it is the newer write.
        supplierCredit:
          (rest as { supplierCredit?: unknown }).supplierCredit ?? vendorCredit
      }
    };
    raw = record;
  }

  const isV2 =
    Array.isArray(record.sourceTypes) ||
    "consolidation" in record ||
    "includeManual" in record;
  if (!isV2) return raw;

  const enabledList = Array.isArray(record.sourceTypes)
    ? record.sourceTypes.filter((v): v is string => typeof v === "string")
    : (POSTING_SYNC_DEFAULT_SOURCE_TYPES as readonly string[]);
  const granularity =
    record.consolidation === "daily" ? "daily-summary" : "individual";

  const sourceTypes: Record<string, { enabled: boolean; granularity: string }> =
    {};
  for (const sourceType of JOURNAL_ENTRY_SOURCE_TYPES) {
    const policy = POSTING_POLICY[sourceType];
    const enabled =
      sourceType === "Manual"
        ? record.includeManual === true
        : policy.representation === "journal" &&
          enabledList.includes(sourceType);
    sourceTypes[sourceType] = { enabled, granularity };
  }

  const {
    consolidation: _consolidation,
    includeManual: _includeManual,
    sourceTypes: _sourceTypes,
    ...rest
  } = record;
  return { ...rest, sourceTypes };
}

const PostingSyncStoredSchema = z.object({
  /**
   * Kept for backward-compatible parsing of stored fragments ONLY (D2:
   * keep-but-ignore). The decision core no longer reads it — posting sync is
   * always-on when an accounting integration is connected.
   */
  enabled: z.boolean().default(true),
  syncFromDate: z.string().optional(),
  /**
   * AR/AP family representation (spec §2): documents (default — native
   * provider documents; journals are DOC_BACKED), journals (documents NOT
   * pushed; the journals push, forced individual), none (explicit opt-out —
   * journals record FAMILY_OFF). Explicit, never derived from entity sync
   * toggles.
   */
  families: z
    .object({
      ar: PostingSyncFamilyModeSchema.default("documents"),
      ap: PostingSyncFamilyModeSchema.default("documents"),
      // Memo families default to "none" deliberately: a family that has never
      // synced has no correct backlog — the accountant has already hand-booked
      // those credits in the provider, so pushing history would double-count.
      // Opt-in, go-forward (set syncFromDate on first enable).
      creditMemo: PostingSyncFamilyModeSchema.default("none"),
      supplierCredit: PostingSyncFamilyModeSchema.default("none")
    })
    .default({
      ar: "documents",
      ap: "documents",
      creditMemo: "none",
      supplierCredit: "none"
    }),
  /** Partial per-source-type overrides; missing entries fill from POSTING_POLICY. */
  sourceTypes: z
    .record(z.string(), PostingSyncSourceTypeConfigSchema)
    .default({}),
  /** Dimension slot config (Phase 2) — empty until dimension sync ships. */
  dimensionSlots: z.array(PostingSyncDimensionSlotSchema).default([]),
  onUnmappedDimensionValue: z.enum(["warn", "drop"]).default("warn"),
  /** park = journals dated in a locked period land Warning; redate = push at lock date + 1 with the original date in the narration. */
  periodLockPolicy: z.enum(["park", "redate"]).default("park"),
  /** Manually captured provider lock date (YYYY-MM-DD) — required for providers whose API cannot report it (QBO); merged with the provider-reported lock date when both exist. */
  lockDate: z.string().optional()
});

/**
 * Per-company posting-sync settings fragment stored at
 * `companyIntegration.metadata.settings.postingSync`. Resolved with
 * `resolvePostingSyncSettings` (core/posting.ts) — never parsed directly
 * from storage, and a bad stored fragment must never break sync. Reads the
 * v3 shape, transparently upgrading stored v2 fragments (see
 * normalizeStoredPostingSyncSettings). The output's `sourceTypes` is TOTAL
 * over the enum (missing entries filled from POSTING_POLICY).
 *
 * `consolidation` in the output is a transitional derived field for the
 * drain/cron hold: "daily" only when every enabled journal-represented type
 * is daily-summary (pure v2-daily shims). Removed once the per-granularity
 * claim filter lands (plan task 1.5).
 */
export const PostingSyncSettingsSchema = z.preprocess(
  normalizeStoredPostingSyncSettings,
  PostingSyncStoredSchema.transform((value) => {
    const sourceTypes = {} as Record<
      JournalEntrySourceType,
      z.infer<typeof PostingSyncSourceTypeConfigSchema>
    >;
    for (const sourceType of JOURNAL_ENTRY_SOURCE_TYPES) {
      sourceTypes[sourceType] = value.sourceTypes[sourceType] ?? {
        enabled: POSTING_POLICY[sourceType].defaultEnabled,
        granularity: POSTING_POLICY[sourceType].defaultGranularity
      };
    }

    // Always-on for the frozen v2 set: those types sync regardless of stored
    // per-type enables. Types shipped defaultEnabled: false (the return
    // journals) are the exception — posting.ts pushes them only when the
    // stored config explicitly enables them, so they are excluded here unless
    // enabled.
    const enabledJournalTypes = JOURNAL_ENTRY_SOURCE_TYPES.filter(
      (sourceType) =>
        POSTING_POLICY[sourceType].representation === "journal" &&
        POSTING_POLICY[sourceType].syncable !== false &&
        (POSTING_POLICY[sourceType].defaultEnabled !== false ||
          sourceTypes[sourceType].enabled)
    );
    const consolidation: "individual" | "daily" =
      enabledJournalTypes.length > 0 &&
      enabledJournalTypes.every(
        (sourceType) => sourceTypes[sourceType].granularity === "daily-summary"
      )
        ? "daily"
        : "individual";

    return { ...value, sourceTypes, consolidation };
  })
);

// ============================================================================
// 4. VALIDATION LOGIC
// ============================================================================

export function validateSyncConfig(config: GlobalSyncConfig): string[] {
  const errors: string[] = [];

  // 1. Validate Dependencies (Always Enforced)
  (Object.keys(config.entities) as AccountingEntityType[]).forEach((entity) => {
    const entityConfig = config.entities[entity];
    const definition = ENTITY_DEFINITIONS[entity];

    if (entityConfig.enabled && definition.dependsOn) {
      definition.dependsOn.forEach((dependency) => {
        if (!config.entities[dependency].enabled) {
          errors.push(
            `Cannot enable '${definition.label}': Missing dependency '${ENTITY_DEFINITIONS[dependency].label}'.`
          );
        }
      });
    }
  });

  // 2. Validate Directions
  (Object.keys(config.entities) as AccountingEntityType[]).forEach((entity) => {
    const entityConfig = config.entities[entity];
    const definition = ENTITY_DEFINITIONS[entity];

    if (
      entityConfig.enabled &&
      !definition.supportedDirections.includes(entityConfig.direction)
    ) {
      errors.push(
        `Entity '${definition.label}' does not support direction '${
          entityConfig.direction
        }'. Supported: ${definition.supportedDirections.join(", ")}`
      );
    }
  });

  return errors;
}

const createEntityConfigSchema = () =>
  z.object({
    enabled: z.boolean().optional().default(true),
    direction: SyncDirectionSchema.optional().default("two-way"),
    owner: z.enum(["carbon", "accounting"]).optional().default("accounting"),
    syncFromDate: z.string().datetime().optional()
  });

export const SyncConfigSchema = z
  .object({
    entities: z
      .object({
        customer: createEntityConfigSchema().optional(),
        vendor: createEntityConfigSchema().optional(),
        item: createEntityConfigSchema().optional(),
        employee: createEntityConfigSchema().optional(),
        purchaseOrder: createEntityConfigSchema().optional(),
        bill: createEntityConfigSchema().optional(),
        salesOrder: createEntityConfigSchema().optional(),
        invoice: createEntityConfigSchema().optional(),
        payment: createEntityConfigSchema().optional(),
        inventoryAdjustment: createEntityConfigSchema().optional(),
        journalEntry: createEntityConfigSchema().optional(),
        charge: createEntityConfigSchema().optional(),
        creditMemo: createEntityConfigSchema().optional(),
        supplierCredit: createEntityConfigSchema().optional(),
        reimbursement: createEntityConfigSchema().optional()
      })
      .optional()
  })
  .optional();

export const ProviderIntegrationMetadataSchema = z.object({
  syncConfig: SyncConfigSchema.optional(),
  credentials: StoredProviderCredentialsSchema.optional(),
  // Per-company integration settings (e.g. settings.postingSync). Kept as a
  // permissive record so parsing never strips or rewrites stored keys —
  // fragments are validated where they are consumed (resolvePostingSyncSettings)
  settings: z.record(z.string(), z.unknown()).optional(),
  // Integration-specific settings (e.g., default account codes for Xero)
  // These are stored at the top level of metadata and passed through to the provider
  defaultSalesAccountCode: z.string().optional(),
  defaultPurchaseAccountCode: z.string().optional()
});

/**
 * Whether an accounting integration may move data. A new connection starts
 * OFF so the customer can map accounts and choose posting settings before
 * anything reaches the provider; it is turned on from the integration drawer,
 * and only once every required account is mapped. Stored at
 * `metadata.settings.syncEnabled`. A row with no flag predates the switch and
 * was already syncing, so absent reads as on — every connect path writes an
 * explicit value.
 */
export function isAccountingSyncEnabled(metadata: unknown): boolean {
  const settings =
    metadata && typeof metadata === "object"
      ? (metadata as { settings?: unknown }).settings
      : undefined;
  if (!settings || typeof settings !== "object") return true;
  return (settings as Record<string, unknown>).syncEnabled !== false;
}

/**
 * The sync switch for an OAuth (re)connection. A reconnect to the SAME
 * provider organization (a Xero tenant, a QuickBooks realm) keeps the switch
 * where it was — an expired grant must not pause an integration that was
 * live. A first connection, or one to a different organization, starts off.
 */
export function syncEnabledOnConnect(
  existingMetadata: unknown,
  organizationId: string
): boolean {
  if (!existingMetadata || typeof existingMetadata !== "object") return false;
  const credentials = (existingMetadata as { credentials?: unknown })
    .credentials as Record<string, unknown> | undefined;
  const providerMetadata = credentials?.providerMetadata as
    | Record<string, unknown>
    | undefined;
  // Legacy rows kept the organization id directly on credentials.
  const previousOrganizationId =
    providerMetadata?.tenantId ??
    providerMetadata?.realmId ??
    credentials?.tenantId ??
    credentials?.realmId;
  return (
    previousOrganizationId === organizationId &&
    isAccountingSyncEnabled(existingMetadata)
  );
}

// /********************************************************\
// *              Sync Operation Schemas                    *
// \********************************************************/

/**
 * Status lifecycle of a sync operation (matches the "syncOperationStatus"
 * Postgres enum): Pending → In Flight → Completed | Failed | Warning |
 * Skipped | Excluded. `Excluded` is a terminal disposition decided by the
 * posting policy (doc-backed, family off, source type disabled) — recorded
 * so completeness is a query; `Skipped` remains the human opt-out.
 */
export const SyncOperationStatusSchema = z.enum([
  "Pending",
  "In Flight",
  "Completed",
  "Failed",
  "Warning",
  "Skipped",
  "Excluded"
]);

export const SyncOperationDirectionSchema = z.enum([
  "push-to-accounting",
  "pull-from-accounting"
]);

export const SyncOperationTriggerSchema = z.enum([
  "event",
  "webhook",
  "backfill",
  "manual",
  "posting",
  "retry",
  // v5: state-derived reconcile decisions (never cooldown-gated)
  "reconcile"
]);

/**
 * A row of the "accountingSyncOperation" ledger: one attempted sync of one
 * entity in one direction.
 */
export const SyncOperationSchema = z.object({
  id: z.string(),
  companyId: z.string(),
  integration: z.string(),
  entityType: z.string(),
  entityId: z.string(),
  direction: SyncOperationDirectionSchema,
  trigger: SyncOperationTriggerSchema,
  status: SyncOperationStatusSchema,
  idempotencyKey: z.string(),
  attemptCount: z.number().int(),
  lastAttemptAt: z.string().nullable(),
  completedAt: z.string().nullable(),
  errorCode: z.string().nullable(),
  errorMessage: z.string().nullable(),
  externalId: z.string().nullable(),
  metadata: z.record(z.string(), z.any()).nullable(),
  createdBy: z.string(),
  createdAt: z.string(),
  updatedBy: z.string().nullable(),
  updatedAt: z.string().nullable()
});

/**
 * UI-driven status transitions: Retry (Failed/Warning/Skipped → Pending
 * — Skipped covers both a human opt-out and the drain's machine no-op
 * close, either of which a user may re-drive), Skip (Failed/Warning/
 * Pending → Skipped), Re-send (Completed/Excluded → Pending — an
 * Excluded journal re-decides against the current policy config).
 * Everything else is invalid.
 */
export const SYNC_OPERATION_ALLOWED_TRANSITIONS: Record<
  z.infer<typeof SyncOperationStatusSchema>,
  ReadonlyArray<z.infer<typeof SyncOperationStatusSchema>>
> = {
  Pending: ["Skipped"],
  "In Flight": [],
  Completed: ["Pending"],
  Failed: ["Pending", "Skipped"],
  Warning: ["Pending", "Skipped"],
  Skipped: ["Pending"],
  Excluded: ["Pending"]
};

export const SyncOperationTransitionSchema = z.object({
  id: z.string(),
  companyId: z.string(),
  to: SyncOperationStatusSchema,
  userId: z.string()
});

// /********************************************************\
// *               Account Mapping Schemas                  *
// \********************************************************/

/**
 * An account in the provider's chart of accounts as fetched from the
 * provider API (e.g. Xero GET /Accounts). `code` is the provider-side
 * account code that matchAccountsByCode compares against Carbon
 * `account.number`.
 */
export const ProviderChartAccountSchema = z.object({
  id: z.string(),
  code: z.string().nullish(),
  name: z.string().nullish()
});

/**
 * Payload for upserting an account mapping (Carbon account.id → provider
 * account id). externalCode/externalName are stored in the mapping
 * metadata for display only — the mapping itself is by id on both sides.
 */
export const UpsertAccountMappingSchema = z.object({
  companyId: z.string(),
  integration: z.string(),
  accountId: z.string(),
  externalId: z.string(),
  externalCode: z.string().optional(),
  externalName: z.string().optional(),
  userId: z.string()
});

// /********************************************************\
// *               Accounting Entity Schemas                *
// \********************************************************/

export const ContactSchema = z.object({
  id: z.string(),
  name: z.string(),
  firstName: z.string(),
  lastName: z.string(),
  companyId: z.string(),
  email: z.string().optional(),
  website: withNullable(z.string().url()),
  taxId: withNullable(z.string()),
  currencyCode: z.string().default("USD"),
  balance: z.number().nullish(),
  creditLimit: z.number().nullish(),
  paymentTerms: z.string().nullish(),
  updatedAt: z.string().datetime(),
  workPhone: withNullable(z.string()),
  mobilePhone: withNullable(z.string()),
  fax: withNullable(z.string()),
  homePhone: withNullable(z.string()),
  isVendor: z.boolean(),
  isCustomer: z.boolean(),
  addresses: z.array(
    z.object({
      label: z.string().nullish(),
      type: z.string().nullish(),
      line1: z.string().nullish(),
      line2: z.string().nullish(),
      city: z.string().nullish(),
      country: z.string().nullish(),
      region: z.string().nullish(),
      postalCode: z.string().nullish()
    })
  ),
  raw: z.record(z.string(), z.any())
});

export const EmployeeSchema = z.object({
  id: z.string(),
  companyId: z.string(),
  firstName: z.string(),
  lastName: z.string(),
  fullName: withNullable(z.string()),
  email: withNullable(z.string().email()),
  active: z.boolean().default(true),
  // Job-related fields from employeeJob
  title: withNullable(z.string()),
  departmentId: withNullable(z.string()),
  locationId: withNullable(z.string()),
  managerId: withNullable(z.string()),
  startDate: withNullable(z.string()),
  // External link (used by Xero)
  externalLink: z
    .object({
      url: withNullable(z.string().url()),
      description: withNullable(z.string())
    })
    .optional(),
  updatedAt: z.string().datetime(),
  raw: z.record(z.string(), z.any()).optional()
});

// ============================================================================
// SALES ORDER (push-only to accounting as Xero Quotes)
// ============================================================================

export const SalesOrderLineSchema = z.object({
  id: z.string(),
  salesOrderLineType: z.string(),
  itemId: withNullable(z.string()),
  itemCode: withNullable(z.string()), // item.readableIdWithRevision
  description: withNullable(z.string()),
  quantity: z.number(),
  unitPrice: z.number(),
  setupPrice: z.number(),
  accountNumber: withNullable(z.string()),
  lineAmount: z.number()
});

export const SalesOrderSchema = z.object({
  id: z.string(),
  salesOrderId: z.string(), // Human-readable SO number
  companyId: z.string(),
  customerId: z.string(),
  customerExternalId: withNullable(z.string()), // Xero ContactID for the customer
  status: z.enum([
    "Draft",
    "Needs Approval",
    "Confirmed",
    "In Progress",
    "To Ship and Invoice",
    "To Ship",
    "To Invoice",
    "Completed",
    "Invoiced",
    "Cancelled",
    "Closed"
  ]),
  orderDate: withNullable(z.string()),
  currencyCode: z.string(),
  exchangeRate: z.number(),
  customerReference: withNullable(z.string()),
  lines: z.array(SalesOrderLineSchema),
  updatedAt: z.string().datetime(),
  raw: z.record(z.string(), z.any()).optional()
});

// Sales Invoice schemas
export const SalesInvoiceLineSchema = z.object({
  id: z.string(),
  invoiceLineType: z.string(),
  itemId: withNullable(z.string()),
  itemCode: withNullable(z.string()), // readableIdWithRevision
  description: withNullable(z.string()),
  quantity: z.number(),
  // BASE currency, matching the stored column.
  unitPrice: z.number(),
  // The document-currency mirror (unitPrice * exchangeRate). Optional because
  // not every provider selects it; push this to any payload that declares a
  // currency code, since unitPrice above is base.
  convertedUnitPrice: withNullable(z.number()).optional(),
  // Line discount, a FRACTION in [0, 1] (the column's CHECK). It discounts the
  // merchandise (quantity × unitPrice) only — add-ons and shipping are never
  // discounted — and applies equally to `unitPrice` and `convertedUnitPrice`,
  // which are both LIST prices. Absent means 0: lines mapped back from a
  // provider carry its net price already.
  discountPercent: z.number().min(0).max(1).optional(),
  shippingCost: z.number().default(0),
  addOnCost: z.number().default(0),
  nonTaxableAddOnCost: z.number().default(0),
  taxPercent: z.number(),
  // Merchandise net of the line discount, in base currency.
  lineAmount: z.number()
});

export const SalesInvoiceSchema = z.object({
  id: z.string(),
  invoiceId: z.string(), // readable ID like "INV-0001"
  companyId: z.string(),
  customerId: z.string(),
  customerExternalId: withNullable(z.string()), // Xero ContactID for the customer
  status: z.enum([
    "Draft",
    "Pending",
    "Submitted",
    "Partially Paid",
    "Paid",
    "Overdue",
    "Voided",
    "Credit Note Issued",
    "Return"
  ]),
  currencyCode: z.string().min(1),
  baseCurrencyCode: z.string().min(1),
  baseCurrencyDecimalPlaces: z.number().int().nonnegative(),
  currencyDecimalPlaces: z.number().int().nonnegative(),
  headerShippingCost: z.number(),
  /** Original posted shipping account; null before posting or when no shipping. */
  shippingRevenueAccountId: z.string().nullable(),
  /**
   * The account the ORIGINAL journal credited for merchandise revenue. Replayed
   * onto the provider document so a historical invoice keeps its own account
   * rather than today's default — the same discipline as shipping above, and
   * load-bearing since AR invoices stopped referencing items (the item used to
   * carry the account implicitly through the provider item's own config).
   */
  salesRevenueAccountId: z.string().nullable(),
  exchangeRate: z.number(),
  postingDate: z.string().nullish(),
  dateIssued: withNullable(z.string()),
  dateDue: withNullable(z.string()),
  datePaid: withNullable(z.string()),
  customerReference: withNullable(z.string()),
  subtotal: z.number(),
  totalTax: z.number(),
  totalDiscount: z.number(),
  totalAmount: z.number(),
  balance: z.number(),
  lines: z.array(SalesInvoiceLineSchema),
  updatedAt: z.string().datetime(),
  raw: z.record(z.string(), z.any()).optional()
});

// Bill (Purchase Invoice) schemas
export const BillLineSchema = z.object({
  id: z.string(),
  description: withNullable(z.string()),
  quantity: z.number(),
  unitPrice: z.number(),
  itemId: withNullable(z.string()),
  itemCode: withNullable(z.string()),
  /** Carbon account.id FK — needed by providers that resolve G/L lines through the account-mapping service (QBO AccountRef). */
  accountId: withNullable(z.string()),
  accountNumber: withNullable(z.string()),
  taxPercent: withNullable(z.number()),
  taxAmount: withNullable(z.number()),
  totalAmount: z.number(),
  purchaseOrderLineId: withNullable(z.string())
});

export const BillSchema = z.object({
  id: z.string(),
  companyId: z.string(),
  invoiceId: z.string(), // Human-readable invoice number
  supplierId: withNullable(z.string()),
  supplierExternalId: withNullable(z.string()), // Xero ContactID for the supplier
  status: z.enum([
    "Draft",
    "Pending",
    "Open",
    "Return",
    "Debit Note Issued",
    "Paid",
    "Partially Paid",
    "Overdue",
    "Voided"
  ]),
  dateIssued: withNullable(z.string()),
  dateDue: withNullable(z.string()),
  datePaid: withNullable(z.string()),
  currencyCode: z.string(),
  exchangeRate: z.number(),
  subtotal: z.number(),
  totalTax: z.number(),
  totalDiscount: z.number(),
  totalAmount: z.number(),
  balance: z.number(),
  supplierReference: withNullable(z.string()),
  lines: z.array(BillLineSchema),
  updatedAt: z.string().datetime(),
  raw: z.record(z.string(), z.any()).optional()
});

// Purchase Order schemas
export const PurchaseOrderLineSchema = z.object({
  id: z.string(),
  description: withNullable(z.string()),
  quantity: z.number(),
  unitPrice: z.number(),
  itemId: withNullable(z.string()),
  itemCode: withNullable(z.string()),
  /** Carbon account.id FK — needed by providers that resolve G/L lines through the account-mapping service (QBO AccountRef). */
  accountId: withNullable(z.string()),
  accountNumber: withNullable(z.string()),
  taxPercent: withNullable(z.number()),
  taxAmount: withNullable(z.number()),
  totalAmount: z.number(),
  quantityReceived: withNullable(z.number()),
  quantityInvoiced: withNullable(z.number())
});

export const PurchaseOrderSchema = z.object({
  id: z.string(),
  companyId: z.string(),
  purchaseOrderId: z.string(), // Human-readable PO number
  supplierId: z.string(),
  supplierExternalId: withNullable(z.string()), // Xero ContactID for the supplier
  status: z.enum([
    "Draft",
    "Needs Approval",
    "To Review",
    "Rejected",
    "To Receive",
    "To Receive and Invoice",
    "To Invoice",
    "Completed",
    "Closed",
    "Planned"
  ]),
  orderDate: withNullable(z.string()),
  deliveryDate: withNullable(z.string()),
  deliveryAddress: withNullable(z.string()),
  deliveryInstructions: withNullable(z.string()),
  currencyCode: withNullable(z.string()),
  exchangeRate: withNullable(z.number()),
  subtotal: z.number(),
  totalTax: z.number(),
  totalAmount: z.number(),
  supplierReference: withNullable(z.string()),
  lines: z.array(PurchaseOrderLineSchema),
  updatedAt: z.string().datetime(),
  raw: z.record(z.string(), z.any()).optional()
});

// ============================================================================
// ITEM (Carbon item synced to accounting system)
// ============================================================================

export const ItemSchema = z.object({
  id: z.string(),
  code: z.string(),
  name: z.string(),
  description: withNullable(z.string()),
  companyId: z.string(),
  // Mirrors the "itemType" Postgres enum. "Service" distinguishes service
  // items for providers whose item objects are typed (QBO Service vs
  // NonInventory).
  type: z.enum([
    "Part",
    "Material",
    "Tool",
    "Service",
    "Consumable",
    "Fixture"
  ]),
  unitOfMeasureCode: withNullable(z.string()),
  unitCost: z.number(),
  unitSalePrice: z.number(),
  isPurchased: z.boolean(),
  isSold: z.boolean(),
  isTrackedAsInventory: z.boolean(),
  updatedAt: z.string(),
  raw: z.record(z.string(), z.any()).optional()
});

// ============================================================================
// INVENTORY ADJUSTMENT (itemLedger-based, push-only to accounting)
// ============================================================================

export const InventoryAdjustmentSchema = z.object({
  id: z.string(),
  entryNumber: z.number(),
  postingDate: z.string(),
  entryType: z.enum(["Positive Adjmt.", "Negative Adjmt."]),
  itemId: z.string(),
  locationId: withNullable(z.string()),
  quantity: z.number(), // positive for positive adj, negative for negative adj
  companyId: z.string(),
  unitCost: z.number(), // from itemCost table
  inventoryAccount: z.string(), // resolved GL account from accountDefault (rawMaterialsAccount for Buy items, finishedGoodsAccount for Make / Buy and Make)
  adjustmentVarianceAccount: z.string(), // GL account code from accountDefault
  updatedAt: z.string().datetime(),
  raw: z.record(z.string(), z.any()).optional()
});

// ============================================================================
// JOURNAL ENTRY (posting sync — journal + journalLine, push-only)
// ============================================================================

/**
 * One analytical dimension stamped on a journal line
 * (`journalLineDimension` row). `valueId` is Carbon's INTERNAL id and is
 * polymorphic across entity-typed dimensions (location.id, supplier.id,
 * item.id, dimensionValue.id, …) — what crosses the wire to a provider is
 * always the RESOLVED provider option id from the dimension value mapping
 * (entityType "dimensionValue"), never this id.
 */
export const JournalEntryLineDimensionSchema = z.object({
  dimensionId: z.string(),
  valueId: z.string()
});

export const JournalEntryLineSchema = z.object({
  id: z.string(),
  accountId: withNullable(z.string()),
  /** Signed: positive = debit, negative = credit. */
  amount: z.number(),
  description: withNullable(z.string()),
  /** Line dimensions (absent when the line carries none). */
  dimensions: z.array(JournalEntryLineDimensionSchema).optional()
});

export const JournalEntrySchema = z.object({
  /** journal.id (Carbon internal id). */
  id: z.string(),
  companyId: z.string(),
  /** Human-readable journal entry number (journal.journalEntryId). */
  journalEntryId: z.string(),
  description: withNullable(z.string()),
  postingDate: z.string(), // YYYY-MM-DD
  status: z.enum(Constants.public.Enums.journalEntryStatus),
  sourceType: withNullable(z.string()), // journalEntrySourceType enum value
  reversalOfId: withNullable(z.string()),
  reversedById: withNullable(z.string()),
  /**
   * True when this fetch is a reversal push (entity id carried the
   * ":reversal" suffix): the syncer pushes negated line amounts for the
   * original journal instead of the journal itself.
   */
  reversal: z.boolean(),
  lines: z.array(JournalEntryLineSchema),
  updatedAt: z.string(),
  raw: z.record(z.string(), z.any()).optional()
});