fullstackgtm 0.10.0

package/src/connectors/hubspotAuth.ts

@@ -0,0 +1,246 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+
+/**
+ * HubSpot CLI authentication.
+ *
+ * Two paths, ordered by how little web they need:
+ * 1. Private app token — no OAuth at all; created once in HubSpot settings.
+ * 2. Bring-your-own-app OAuth with an RFC 8252 loopback redirect — the
+ *    browser is used for exactly one thing (the consent grant); the CLI
+ *    captures the code on 127.0.0.1 and performs the exchange itself.
+ *
+ * HubSpot does not support the device-authorization grant or PKCE-only
+ * public clients, so the loopback flow requires the user's own app client
+ * id/secret, which are kept locally for silent refresh.
+ */
+
+const HS_AUTH_URL = "https://app.hubspot.com/oauth/authorize";
+const HS_TOKEN_URL = "https://api.hubapi.com/oauth/v1/token";
+const HS_API_URL = "https://api.hubapi.com";
+
+export const DEFAULT_OAUTH_SCOPES = [
+  "crm.objects.deals.read",
+  "crm.objects.owners.read",
+  "crm.objects.companies.read",
+  "crm.objects.contacts.read",
+  "crm.objects.deals.write",
+];
+
+export const DEFAULT_LOOPBACK_PORT = 8763;
+
+/**
+ * OAuth error responses can echo request parameters (client_secret, code).
+ * Surface only the standard `error`/`error_description` fields, never the raw
+ * body, so secrets never reach logs.
+ */
+async function safeTokenError(response: Response): Promise<string> {
+  let description: string | undefined;
+  try {
+    const data = await response.json();
+    description = data?.error_description ?? data?.error ?? data?.message;
+  } catch {
+    // Non-JSON body — withhold it entirely.
+  }
+  return description
+    ? `${response.status} (${String(description).slice(0, 200)})`
+    : `HTTP ${response.status} ${response.statusText}`.trim();
+}
+
+export type HubspotTokenSet = {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: number;
+};
+
+export async function validateHubspotToken(
+  token: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; detail: string }> {
+  const response = await fetchImpl(`${HS_API_URL}/crm/v3/owners?limit=1`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (response.ok) {
+    return { ok: true, detail: "Token accepted by the HubSpot CRM API." };
+  }
+  const body = await response.text();
+  return { ok: false, detail: `HubSpot rejected the token (${response.status}): ${body}` };
+}
+
+async function tokenRequest(
+  params: Record<string, string>,
+  fetchImpl: typeof fetch,
+): Promise<HubspotTokenSet> {
+  const response = await fetchImpl(HS_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(params).toString(),
+  });
+  if (!response.ok) {
+    throw new Error(`HubSpot token request failed: ${await safeTokenError(response)}`);
+  }
+  const data = await response.json();
+  if (!data.access_token) throw new Error("HubSpot token response had no access_token.");
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresAt: Date.now() + (data.expires_in ?? 1800) * 1000,
+  };
+}
+
+export async function exchangeHubspotCode(options: {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  code: string;
+  fetchImpl?: typeof fetch;
+}): Promise<HubspotTokenSet> {
+  return tokenRequest(
+    {
+      grant_type: "authorization_code",
+      client_id: options.clientId,
+      client_secret: options.clientSecret,
+      redirect_uri: options.redirectUri,
+      code: options.code,
+    },
+    options.fetchImpl ?? fetch,
+  );
+}
+
+export async function refreshHubspotToken(options: {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+  fetchImpl?: typeof fetch;
+}): Promise<HubspotTokenSet> {
+  return tokenRequest(
+    {
+      grant_type: "refresh_token",
+      client_id: options.clientId,
+      client_secret: options.clientSecret,
+      refresh_token: options.refreshToken,
+    },
+    options.fetchImpl ?? fetch,
+  );
+}
+
+export type LoopbackLoginOptions = {
+  clientId: string;
+  clientSecret: string;
+  /** Must match a redirect URL registered on the HubSpot app: http://localhost:<port>/callback */
+  port?: number;
+  scopes?: string[];
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  /** Receives the authorize URL; default prints it and best-effort opens a browser. */
+  openUrl?: (url: string) => void | Promise<void>;
+  log?: (message: string) => void;
+};
+
+/**
+ * RFC 8252 loopback OAuth: serve one request on 127.0.0.1, send the user to
+ * the provider consent page, capture the code locally, exchange it directly.
+ */
+export async function runHubspotLoopbackLogin(
+  options: LoopbackLoginOptions,
+): Promise<HubspotTokenSet> {
+  const port = options.port ?? DEFAULT_LOOPBACK_PORT;
+  const scopes = options.scopes ?? DEFAULT_OAUTH_SCOPES;
+  const log = options.log ?? ((message: string) => console.error(message));
+  const redirectUri = `http://localhost:${port}/callback`;
+  const state = randomBytes(16).toString("hex");
+
+  const code = await new Promise<string>((resolve, reject) => {
+    const server = createServer((request, response) => {
+      const url = new URL(request.url ?? "/", `http://localhost:${port}`);
+      if (url.pathname !== "/callback") {
+        response.writeHead(404).end();
+        return;
+      }
+      const receivedState = url.searchParams.get("state");
+      const receivedCode = url.searchParams.get("code");
+      const error = url.searchParams.get("error");
+      response.writeHead(200, { "Content-Type": "text/html" });
+      response.end(
+        "<html><body><p>FullStackGTM CLI login complete. You can close this tab.</p></body></html>",
+      );
+      server.close();
+      clearTimeout(timer);
+      if (error) {
+        reject(new Error(`HubSpot authorization failed: ${error}`));
+      } else if (receivedState !== state) {
+        reject(new Error("OAuth state mismatch; aborting login."));
+      } else if (!receivedCode) {
+        reject(new Error("HubSpot redirected without an authorization code."));
+      } else {
+        resolve(receivedCode);
+      }
+    });
+
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error("Timed out waiting for the OAuth redirect."));
+    }, options.timeoutMs ?? 5 * 60 * 1000);
+
+    server.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    server.listen(port, "127.0.0.1", () => {
+      const authorizeUrl =
+        `${HS_AUTH_URL}?` +
+        new URLSearchParams({
+          response_type: "code",
+          client_id: options.clientId,
+          redirect_uri: redirectUri,
+          scope: scopes.join(" "),
+          state,
+        }).toString();
+      log(`Open this URL to authorize (waiting on ${redirectUri}):\n\n  ${authorizeUrl}\n`);
+      void (options.openUrl ?? openInBrowser)(authorizeUrl);
+    });
+  });
+
+  return exchangeHubspotCode({
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+    redirectUri,
+    code,
+    fetchImpl: options.fetchImpl,
+  });
+}
+
+export async function openInBrowser(url: string) {
+  // The URL may come from an external source (e.g. a broker deployment's
+  // verification URL). Only ever hand a well-formed http(s) URL to the OS
+  // opener — this prevents a leading `-` from being read as a flag by
+  // xdg-open and refuses non-web schemes outright.
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return;
+  const safeUrl = parsed.toString();
+
+  const { spawn } = await import("node:child_process");
+  try {
+    if (process.platform === "darwin") {
+      spawn("open", [safeUrl], { stdio: "ignore", detached: true }).on("error", () => {});
+    } else if (process.platform === "win32") {
+      // `start` is a cmd builtin, not an executable; the empty "" is the
+      // window title so a URL with characters isn't mis-parsed as the title.
+      spawn("cmd", ["/c", "start", "", safeUrl], { stdio: "ignore", detached: true }).on(
+        "error",
+        () => {},
+      );
+    } else {
+      // `--` ends option parsing so the URL is never treated as a flag.
+      spawn("xdg-open", ["--", safeUrl], { stdio: "ignore", detached: true }).on("error", () => {});
+    }
+  } catch {
+    // Printing the URL is the contract; opening a browser is best-effort.
+  }
+}

package/src/connectors/salesforce.ts

@@ -0,0 +1,420 @@
+import {
+  SALESFORCE_DEFAULT_FIELD_MAPPINGS,
+  mappedField,
+  mappedFields,
+  readMappedValue,
+  type CrmObjectType,
+  type FieldMappings,
+} from "../mappings.ts";
+import type {
+  CanonicalAccount,
+  CanonicalContact,
+  CanonicalDeal,
+  CanonicalGtmSnapshot,
+  CanonicalUser,
+  GtmConnector,
+  GtmObjectType,
+  PatchOperation,
+  PatchOperationResult,
+} from "../types.ts";
+
+const DEFAULT_API_VERSION = "v59.0";
+
+export type SalesforceConnection = {
+  accessToken: string;
+  /** e.g. https://yourorg.my.salesforce.com */
+  instanceUrl: string;
+};
+
+export type SalesforceConnectorOptions = {
+  /** Returns an access token plus the instance URL it belongs to. */
+  getConnection: () => SalesforceConnection | Promise<SalesforceConnection>;
+  /** Per-org canonical-to-provider field overrides. Defaults cover standard fields. */
+  fieldMappings?: FieldMappings;
+  apiVersion?: string;
+  /** Injectable fetch for testing. */
+  fetchImpl?: typeof fetch;
+};
+
+const SOBJECT_TYPES: Partial<Record<GtmObjectType, string>> = {
+  account: "Account",
+  contact: "Contact",
+  deal: "Opportunity",
+};
+
+const MAPPING_OBJECT_TYPES: Partial<Record<GtmObjectType, Exclude<CrmObjectType, "owners">>> = {
+  account: "accounts",
+  contact: "contacts",
+  deal: "deals",
+};
+
+/**
+ * Reference connector for Salesforce.
+ *
+ * Reads run SOQL with cursor pagination; writes PATCH sobjects directly.
+ * Like the HubSpot connector, it never drops records it cannot fully resolve
+ * (ownerless or amountless opportunities are returned so audit rules can
+ * surface the gaps). Probabilities are normalized to 0..1 to match the
+ * canonical model.
+ */
+export function createSalesforceConnector(
+  options: SalesforceConnectorOptions,
+): Required<GtmConnector> {
+  const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const mappings = options.fieldMappings;
+
+  async function request(path: string, init: RequestInit = {}): Promise<any> {
+    const connection = await options.getConnection();
+    const url = path.startsWith("http")
+      ? path
+      : `${connection.instanceUrl.replace(/\/$/, "")}${path}`;
+    const response = await fetchImpl(url, {
+      ...init,
+      headers: {
+        Authorization: `Bearer ${connection.accessToken}`,
+        "Content-Type": "application/json",
+        ...(init.headers ?? {}),
+      },
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Salesforce API error ${response.status}: ${body}`);
+    }
+    // Salesforce PATCH returns 204 No Content on success.
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
+  }
+
+  async function query(soql: string): Promise<any[]> {
+    const records: any[] = [];
+    let next: string | undefined = `/services/data/${apiVersion}/query?q=${encodeURIComponent(soql)}`;
+    const seen = new Set<string>();
+    while (next) {
+      // Defend against a repeated nextRecordsUrl (would loop forever).
+      if (seen.has(next)) break;
+      seen.add(next);
+      const data = await request(next);
+      records.push(...(data?.records ?? []));
+      next = data?.nextRecordsUrl ?? undefined;
+    }
+    return records;
+  }
+
+  function readMapped(
+    source: Record<string, unknown>,
+    objectType: CrmObjectType,
+    targetField: string,
+    fallbackField: string,
+  ) {
+    return readMappedValue(source, mappings, objectType, targetField, fallbackField);
+  }
+
+  function selectFields(objectType: CrmObjectType) {
+    return mappedFields(
+      mappings,
+      objectType,
+      SALESFORCE_DEFAULT_FIELD_MAPPINGS[objectType],
+    ).join(", ");
+  }
+
+  async function assembleSnapshot(whereClause: string): Promise<CanonicalGtmSnapshot> {
+    const sfUsers = await query(`SELECT ${selectFields("owners")} FROM User${whereClause}`);
+    const users: CanonicalUser[] = sfUsers.map((user) => {
+      const id = String(readMapped(user, "owners", "id", "Id"));
+      const email = stringOrUndefined(readMapped(user, "owners", "email", "Email"));
+      return {
+        id,
+        provider: "salesforce",
+        crmId: id,
+        identities: [{ provider: "salesforce", externalId: id }],
+        name: stringOrFallback(readMapped(user, "owners", "name", "Name"), email ?? `User ${id}`),
+        email,
+        title: stringOrUndefined(readMapped(user, "owners", "title", "Title")),
+        active: Boolean(readMapped(user, "owners", "isActive", "IsActive")),
+      };
+    });
+
+    const sfAccounts = await query(
+      `SELECT ${selectFields("accounts")} FROM Account${whereClause}`,
+    );
+    const accounts: CanonicalAccount[] = sfAccounts.map((account) => {
+      const id = String(readMapped(account, "accounts", "id", "Id"));
+      return {
+        id,
+        provider: "salesforce",
+        crmId: id,
+        identities: [{ provider: "salesforce", externalId: id }],
+        name: stringOrFallback(readMapped(account, "accounts", "name", "Name"), "Unknown Account"),
+        domain: stringOrUndefined(readMapped(account, "accounts", "domain", "Website")),
+        industry: stringOrUndefined(readMapped(account, "accounts", "industry", "Industry")),
+        employeeCount: numberOrUndefined(
+          readMapped(account, "accounts", "employeeCount", "NumberOfEmployees"),
+        ),
+        annualRevenue: numberOrUndefined(
+          readMapped(account, "accounts", "annualRevenue", "AnnualRevenue"),
+        ),
+        ownerId: stringOrUndefined(readMapped(account, "accounts", "ownerId", "OwnerId")),
+        raw: account,
+      };
+    });
+
+    const sfContacts = await query(
+      `SELECT ${selectFields("contacts")} FROM Contact${whereClause}`,
+    );
+    const contacts: CanonicalContact[] = sfContacts.map((contact) => {
+      const id = String(readMapped(contact, "contacts", "id", "Id"));
+      return {
+        id,
+        provider: "salesforce",
+        crmId: id,
+        identities: [{ provider: "salesforce", externalId: id }],
+        accountId: stringOrUndefined(readMapped(contact, "contacts", "accountId", "AccountId")),
+        firstName: stringOrUndefined(readMapped(contact, "contacts", "firstName", "FirstName")),
+        lastName: stringOrUndefined(readMapped(contact, "contacts", "lastName", "LastName")),
+        email: stringOrUndefined(readMapped(contact, "contacts", "email", "Email")),
+        phone: stringOrUndefined(readMapped(contact, "contacts", "phone", "Phone")),
+        title: stringOrUndefined(readMapped(contact, "contacts", "title", "Title")),
+        ownerId: stringOrUndefined(readMapped(contact, "contacts", "ownerId", "OwnerId")),
+        raw: contact,
+      };
+    });
+
+    const sfOpportunities = await query(
+      `SELECT ${selectFields("deals")} FROM Opportunity${whereClause}`,
+    );
+    const deals: CanonicalDeal[] = sfOpportunities.map((opportunity) => {
+      const id = String(readMapped(opportunity, "deals", "id", "Id"));
+      const probability = numberOrUndefined(
+        readMapped(opportunity, "deals", "probability", "Probability"),
+      );
+      const isClosed = Boolean(readMapped(opportunity, "deals", "isClosed", "IsClosed"));
+      const isWon = Boolean(readMapped(opportunity, "deals", "isWon", "IsWon"));
+      const forecastCategoryName = stringOrUndefined(
+        readMapped(opportunity, "deals", "forecastCategoryName", "ForecastCategory"),
+      );
+      const forecastCategory = isWon
+        ? "closed_won"
+        : isClosed
+          ? "closed_lost"
+          : // Map Salesforce's native ForecastCategory (e.g. "BestCase",
+            // "Commit", "Pipeline") to the canonical snake_case form, falling
+            // back to "pipeline" when absent.
+            (forecastCategoryName
+              ? forecastCategoryName
+                  .replace(/([a-z])([A-Z])/g, "$1_$2")
+                  .toLowerCase()
+              : "pipeline");
+      return {
+        id,
+        provider: "salesforce",
+        crmId: id,
+        identities: [{ provider: "salesforce", externalId: id }],
+        accountId: stringOrUndefined(readMapped(opportunity, "deals", "accountId", "AccountId")),
+        ownerId: stringOrUndefined(readMapped(opportunity, "deals", "ownerId", "OwnerId")),
+        name: stringOrFallback(readMapped(opportunity, "deals", "name", "Name"), "Untitled Opportunity"),
+        amount: numberOrUndefined(readMapped(opportunity, "deals", "amount", "Amount")),
+        stage: stringOrUndefined(readMapped(opportunity, "deals", "stage", "StageName")),
+        closeDate: stringOrUndefined(
+          readMapped(opportunity, "deals", "closeDate", "CloseDate"),
+        )?.split("T")[0],
+        dealType: stringOrUndefined(readMapped(opportunity, "deals", "dealType", "Type")),
+        forecastCategory,
+        // Salesforce probabilities are 0..100; canonical is 0..1.
+        probability: probability === undefined ? undefined : probability / 100,
+        isClosed,
+        isWon,
+        lastActivityAt: stringOrUndefined(
+          readMapped(opportunity, "deals", "lastActivityAt", "LastActivityDate"),
+        ),
+        raw: opportunity,
+      };
+    });
+
+    return {
+      generatedAt: new Date().toISOString(),
+      provider: "salesforce",
+      users,
+      accounts,
+      contacts,
+      deals,
+      // Task/Event reads come with engagement support; staleness falls back
+      // to close dates until then.
+      activities: [],
+    };
+  }
+
+  async function fetchSnapshot(): Promise<CanonicalGtmSnapshot> {
+    return assembleSnapshot("");
+  }
+
+  /** Records modified since `sinceIso`, filtered on `SystemModstamp`. */
+  async function fetchChanges(sinceIso: string): Promise<CanonicalGtmSnapshot> {
+    const sinceMs = Date.parse(sinceIso);
+    if (!Number.isFinite(sinceMs)) throw new Error(`Invalid since timestamp: ${sinceIso}`);
+    return assembleSnapshot(` WHERE SystemModstamp >= ${new Date(sinceMs).toISOString()}`);
+  }
+
+  function humanizeField(field: string): string {
+    return field
+      .replace(/_task$/, "")
+      .replace(/[_-]+/g, " ")
+      .replace(/\b\w/g, (c) => c.toUpperCase())
+      .trim();
+  }
+
+  async function setField(operation: PatchOperation): Promise<PatchOperationResult> {
+    const sobjectType = SOBJECT_TYPES[operation.objectType];
+    const mappingType = MAPPING_OBJECT_TYPES[operation.objectType];
+    if (!sobjectType || !mappingType || !operation.field) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: "Field writes are only supported for accounts, contacts, and deals with an explicit field.",
+      };
+    }
+    const defaults = SALESFORCE_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+    const field = mappedField(
+      mappings,
+      mappingType,
+      operation.field,
+      defaults[operation.field] ?? operation.field,
+    );
+    const value =
+      operation.operation === "clear_field" ? null : String(operation.afterValue ?? "");
+    await request(
+      `/services/data/${apiVersion}/sobjects/${sobjectType}/${encodeURIComponent(operation.objectId)}`,
+      { method: "PATCH", body: JSON.stringify({ [field]: value }) },
+    );
+    return {
+      operationId: operation.id,
+      status: "applied",
+      detail: `Set ${field} on ${sobjectType}/${operation.objectId}.`,
+      providerData: { sobjectType, field },
+    };
+  }
+
+  async function createTask(operation: PatchOperation): Promise<PatchOperationResult> {
+    // Salesforce activities relate via WhatId (account/opportunity) or WhoId
+    // (contact). Subject is required.
+    const reference =
+      operation.objectType === "contact"
+        ? { WhoId: operation.objectId }
+        : operation.objectType === "account" || operation.objectType === "deal"
+          ? { WhatId: operation.objectId }
+          : null;
+    if (!reference) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: "Tasks can be attached to accounts, contacts, and deals.",
+      };
+    }
+    const response = await request(`/services/data/${apiVersion}/sobjects/Task`, {
+      method: "POST",
+      body: JSON.stringify({
+        Subject: operation.field ? humanizeField(operation.field) : "Follow up",
+        Description: String(operation.afterValue ?? operation.reason ?? ""),
+        Status: "Not Started",
+        Priority: "Normal",
+        ...reference,
+      }),
+    });
+    return {
+      operationId: operation.id,
+      status: "applied",
+      detail: `Created task on ${operation.objectType}/${operation.objectId}.`,
+      providerData: { id: (response as { id?: string })?.id },
+    };
+  }
+
+  async function archiveRecord(operation: PatchOperation): Promise<PatchOperationResult> {
+    const sobjectType = SOBJECT_TYPES[operation.objectType];
+    if (!sobjectType) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: "archive_record is supported for accounts, contacts, and deals.",
+      };
+    }
+    await request(
+      `/services/data/${apiVersion}/sobjects/${sobjectType}/${encodeURIComponent(operation.objectId)}`,
+      { method: "DELETE" },
+    );
+    return {
+      operationId: operation.id,
+      status: "applied",
+      detail: `Deleted ${sobjectType}/${operation.objectId}.`,
+    };
+  }
+
+  async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
+    try {
+      switch (operation.operation) {
+        case "set_field":
+        case "clear_field":
+          // link_record on a deal is just setting AccountId in Salesforce.
+          return await setField(operation);
+        case "link_record":
+          return await setField({ ...operation, operation: "set_field" });
+        case "create_task":
+          return await createTask(operation);
+        case "archive_record":
+          return await archiveRecord(operation);
+        default:
+          return {
+            operationId: operation.id,
+            status: "skipped",
+            detail: `Unknown operation ${operation.operation}.`,
+          };
+      }
+    } catch (error) {
+      return {
+        operationId: operation.id,
+        status: "failed",
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  async function readField(
+    objectType: GtmObjectType,
+    objectId: string,
+    field: string,
+  ): Promise<unknown> {
+    const sobjectType = SOBJECT_TYPES[objectType];
+    const mappingType = MAPPING_OBJECT_TYPES[objectType];
+    if (!sobjectType || !mappingType) {
+      throw new Error(`Field reads are only supported for accounts, contacts, and deals.`);
+    }
+    const defaults = SALESFORCE_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+    const sfField = mappedField(mappings, mappingType, field, defaults[field] ?? field);
+    const data = await request(
+      `/services/data/${apiVersion}/sobjects/${sobjectType}/${encodeURIComponent(objectId)}?fields=${encodeURIComponent(sfField)}`,
+    );
+    return data?.[sfField] ?? null;
+  }
+
+  return {
+    provider: "salesforce",
+    fetchSnapshot,
+    fetchChanges,
+    applyOperation,
+    readField,
+  };
+}
+
+function stringOrUndefined(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  return String(value);
+}
+
+function stringOrFallback(value: unknown, fallback: string): string {
+  return stringOrUndefined(value) ?? fallback;
+}
+
+function numberOrUndefined(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const parsed = typeof value === "number" ? value : Number.parseFloat(String(value));
+  return Number.isFinite(parsed) ? parsed : undefined;
+}