opencode-gateway 0.1.0

package/dist/cli.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+
+// src/cli/args.ts
+import { resolve } from "node:path";
+function parseCliCommand(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    return { kind: "help" };
+  }
+  if (command !== "init" && command !== "doctor") {
+    throw new Error(`unknown command: ${command}`);
+  }
+  let managed = false;
+  let configDir = null;
+  for (let index = 0;index < rest.length; index += 1) {
+    const argument = rest[index];
+    if (argument === "--managed") {
+      managed = true;
+      continue;
+    }
+    if (argument === "--config-dir") {
+      const value = rest[index + 1];
+      if (!value) {
+        throw new Error("--config-dir requires a value");
+      }
+      configDir = resolve(value);
+      index += 1;
+      continue;
+    }
+    if (argument === "--help" || argument === "-h") {
+      return { kind: "help" };
+    }
+    throw new Error(`unknown argument: ${argument}`);
+  }
+  if (managed && configDir !== null) {
+    throw new Error("--managed cannot be combined with --config-dir");
+  }
+  return {
+    kind: command,
+    managed,
+    configDir
+  };
+}
+function formatCliHelp() {
+  return [
+    "opencode-gateway",
+    "",
+    "Commands:",
+    "  opencode-gateway init [--managed] [--config-dir <path>]",
+    "  opencode-gateway doctor [--managed] [--config-dir <path>]",
+    "",
+    "Defaults:",
+    "  init/doctor use OPENCODE_CONFIG_DIR when set, otherwise ~/.config/opencode",
+    "  --managed uses ~/.config/opencode-gateway/opencode"
+  ].join(`
+`);
+}
+
+// src/cli/doctor.ts
+import { readFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+
+// src/config/paths.ts
+import { homedir } from "node:os";
+import { join, resolve as resolve2 } from "node:path";
+var GATEWAY_CONFIG_FILE = "opencode-gateway.toml";
+var OPENCODE_CONFIG_FILE = "opencode.json";
+function resolveOpencodeConfigDir(env) {
+  const explicit = env.OPENCODE_CONFIG_DIR;
+  if (explicit && explicit.trim().length > 0) {
+    return resolve2(explicit);
+  }
+  return defaultOpencodeConfigDir(env);
+}
+function resolveManagedOpencodeConfigDir(env) {
+  return join(resolveConfigHome(env), "opencode-gateway", "opencode");
+}
+function defaultGatewayStateDbPath(env) {
+  return join(resolveDataHome(env), "opencode-gateway", "state.db");
+}
+function resolveConfigHome(env) {
+  return env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+}
+function resolveDataHome(env) {
+  return env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+}
+function defaultOpencodeConfigDir(env) {
+  return join(resolveConfigHome(env), "opencode");
+}
+
+// src/cli/opencode-config.ts
+var OPENCODE_SCHEMA_URL = "https://opencode.ai/config.json";
+var PACKAGE_NAME = "opencode-gateway";
+function createDefaultOpencodeConfig(managed) {
+  const document = {
+    $schema: OPENCODE_SCHEMA_URL,
+    plugin: [PACKAGE_NAME]
+  };
+  if (managed) {
+    document.server = {
+      hostname: "127.0.0.1",
+      port: 4096
+    };
+  }
+  return document;
+}
+function ensureGatewayPlugin(document) {
+  const plugins = document.plugin;
+  if (plugins === undefined) {
+    return {
+      changed: true,
+      document: {
+        ...document,
+        plugin: [PACKAGE_NAME]
+      }
+    };
+  }
+  if (!Array.isArray(plugins)) {
+    throw new Error("opencode.json field `plugin` must be an array when present");
+  }
+  if (plugins.some((entry) => entry === PACKAGE_NAME)) {
+    return {
+      changed: false,
+      document
+    };
+  }
+  return {
+    changed: true,
+    document: {
+      ...document,
+      plugin: [...plugins, PACKAGE_NAME]
+    }
+  };
+}
+function parseOpencodeConfig(source, path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (error) {
+    throw new Error(`failed to parse opencode config ${path}: ${formatError(error)}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`opencode config ${path} must decode to a JSON object`);
+  }
+  return parsed;
+}
+function stringifyOpencodeConfig(document) {
+  return `${JSON.stringify(document, null, 2)}
+`;
+}
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/cli/paths.ts
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve as resolve3 } from "node:path";
+function resolveCliConfigDir(options, env) {
+  if (options.configDir !== null) {
+    return resolve3(options.configDir);
+  }
+  if (options.managed) {
+    return resolveManagedOpencodeConfigDir(env);
+  }
+  return resolveOpencodeConfigDir(env);
+}
+async function pathExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/cli/doctor.ts
+async function runDoctor(options, env) {
+  const configDir = resolveCliConfigDir(options, env);
+  const opencodeConfigPath = join2(configDir, OPENCODE_CONFIG_FILE);
+  const gatewayConfigPath = join2(configDir, GATEWAY_CONFIG_FILE);
+  const opencodeStatus = await inspectOpencodeConfig(opencodeConfigPath);
+  const gatewayOverride = env.OPENCODE_GATEWAY_CONFIG?.trim() || null;
+  console.log("doctor report");
+  console.log(`  config dir: ${configDir}`);
+  console.log(`  opencode config: ${await describePath(opencodeConfigPath)}`);
+  console.log(`  gateway config: ${await describePath(gatewayConfigPath)}`);
+  console.log(`  gateway config override: ${gatewayOverride ?? "not set"}`);
+  console.log(`  plugin configured: ${opencodeStatus.pluginConfigured}`);
+  console.log(`  TELEGRAM_BOT_TOKEN: ${env.TELEGRAM_BOT_TOKEN?.trim() ? "set" : "missing"}`);
+  if (opencodeStatus.error !== null) {
+    console.log(`  opencode config error: ${opencodeStatus.error}`);
+  }
+}
+async function describePath(path) {
+  return await pathExists(path) ? `present at ${path}` : `missing at ${path}`;
+}
+async function inspectOpencodeConfig(path) {
+  if (!await pathExists(path)) {
+    return {
+      pluginConfigured: "no",
+      error: null
+    };
+  }
+  try {
+    const parsed = parseOpencodeConfig(await readFile(path, "utf8"), path);
+    const plugins = parsed.plugin;
+    if (plugins === undefined) {
+      return {
+        pluginConfigured: "no",
+        error: null
+      };
+    }
+    if (!Array.isArray(plugins)) {
+      return {
+        pluginConfigured: "invalid",
+        error: "`plugin` is not an array"
+      };
+    }
+    return {
+      pluginConfigured: plugins.some((entry) => entry === "opencode-gateway") ? "yes" : "no",
+      error: null
+    };
+  } catch (error) {
+    return {
+      pluginConfigured: "unknown",
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/cli/init.ts
+import { mkdir, readFile as readFile2, writeFile } from "node:fs/promises";
+import { dirname, join as join3 } from "node:path";
+
+// src/cli/templates.ts
+function buildGatewayConfigTemplate(stateDbPath) {
+  return [
+    "# Opencode Gateway configuration",
+    "# Fill in secrets and provider details before enabling real integrations.",
+    "",
+    "[gateway]",
+    `state_db = "${escapeTomlString(stateDbPath)}"`,
+    "",
+    "[cron]",
+    "enabled = true",
+    "tick_seconds = 5",
+    "max_concurrent_runs = 1",
+    '# timezone = "Asia/Shanghai"',
+    "",
+    "[channels.telegram]",
+    "enabled = false",
+    'bot_token_env = "TELEGRAM_BOT_TOKEN"',
+    "poll_timeout_seconds = 25",
+    "allowed_chats = []",
+    "allowed_users = []",
+    ""
+  ].join(`
+`);
+}
+function escapeTomlString(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', "\\\"");
+}
+
+// src/cli/init.ts
+async function runInit(options, env) {
+  const configDir = resolveCliConfigDir(options, env);
+  const opencodeConfigPath = join3(configDir, OPENCODE_CONFIG_FILE);
+  const gatewayConfigPath = join3(configDir, GATEWAY_CONFIG_FILE);
+  await mkdir(configDir, { recursive: true });
+  let opencodeStatus = "already present";
+  if (!await pathExists(opencodeConfigPath)) {
+    await writeFile(opencodeConfigPath, stringifyOpencodeConfig(createDefaultOpencodeConfig(options.managed)));
+    opencodeStatus = "created";
+  } else {
+    const source = await readFile2(opencodeConfigPath, "utf8");
+    const parsed = parseOpencodeConfig(source, opencodeConfigPath);
+    const next = ensureGatewayPlugin(parsed);
+    if (next.changed) {
+      await writeFile(opencodeConfigPath, stringifyOpencodeConfig(next.document));
+      opencodeStatus = "updated";
+    }
+  }
+  let gatewayStatus = "already present";
+  if (!await pathExists(gatewayConfigPath)) {
+    await mkdir(dirname(gatewayConfigPath), { recursive: true });
+    await writeFile(gatewayConfigPath, buildGatewayConfigTemplate(defaultGatewayStateDbPath(env)));
+    gatewayStatus = "created";
+  }
+  console.log(`config dir: ${configDir}`);
+  console.log(`opencode config: ${opencodeConfigPath} (${opencodeStatus})`);
+  console.log(`gateway config: ${gatewayConfigPath} (${gatewayStatus})`);
+}
+
+// src/cli.ts
+async function main() {
+  const command = parseCliCommand(process.argv.slice(2));
+  switch (command.kind) {
+    case "help":
+      console.log(formatCliHelp());
+      return;
+    case "doctor":
+      await runDoctor(command, process.env);
+      return;
+    case "init":
+      await runInit(command, process.env);
+      return;
+  }
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`error: ${message}`);
+  process.exitCode = 1;
+});

package/dist/config/cron.d.ts

@@ -0,0 +1,7 @@
+export type CronConfig = {
+    enabled: boolean;
+    tickSeconds: number;
+    maxConcurrentRuns: number;
+    timezone: string | null;
+};
+export declare function parseCronConfig(value: unknown): CronConfig;

package/dist/config/cron.js

@@ -0,0 +1,52 @@
+export function parseCronConfig(value) {
+    const table = readCronTable(value);
+    return {
+        enabled: readBoolean(table.enabled, "cron.enabled", true),
+        tickSeconds: readPositiveInteger(table.tick_seconds, "cron.tick_seconds", 5),
+        maxConcurrentRuns: readPositiveInteger(table.max_concurrent_runs, "cron.max_concurrent_runs", 1),
+        timezone: readOptionalString(table.timezone, "cron.timezone"),
+    };
+}
+function readCronTable(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("cron must be a table when present");
+    }
+    return value;
+}
+function readBoolean(value, field, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${field} must be a boolean when present`);
+    }
+    return value;
+}
+function readPositiveInteger(value, field, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new Error(`${field} must be an integer when present`);
+    }
+    if (value < 1) {
+        throw new Error(`${field} must be greater than or equal to 1`);
+    }
+    return value;
+}
+function readOptionalString(value, field) {
+    if (value === undefined) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${field} must be a string when present`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${field} must not be empty when present`);
+    }
+    return trimmed;
+}

package/dist/config/gateway.d.ts

@@ -0,0 +1,26 @@
+import { type CronConfig } from "./cron";
+import { type TelegramConfig } from "./telegram";
+export type GatewayMailboxRouteConfig = {
+    channel: string;
+    target: string;
+    topic: string | null;
+    mailboxKey: string;
+};
+export type GatewayMailboxConfig = {
+    batchReplies: boolean;
+    batchWindowMs: number;
+    routes: GatewayMailboxRouteConfig[];
+};
+export type GatewayConfig = {
+    configPath: string;
+    stateDbPath: string;
+    mediaRootPath: string;
+    hasLegacyGatewayTimezone: boolean;
+    legacyGatewayTimezone: string | null;
+    mailbox: GatewayMailboxConfig;
+    cron: CronConfig;
+    telegram: TelegramConfig;
+};
+type EnvSource = Record<string, string | undefined>;
+export declare function loadGatewayConfig(env?: EnvSource): Promise<GatewayConfig>;
+export {};

package/dist/config/gateway.js

@@ -0,0 +1,142 @@
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { parseCronConfig } from "./cron";
+import { defaultGatewayStateDbPath, resolveGatewayConfigPath } from "./paths";
+import { parseTelegramConfig } from "./telegram";
+export async function loadGatewayConfig(env = process.env) {
+    const configPath = resolveGatewayConfigPath(env);
+    const rawConfig = await readGatewayConfigFile(configPath);
+    const stateDbValue = rawConfig?.gateway?.state_db;
+    if (stateDbValue !== undefined && typeof stateDbValue !== "string") {
+        throw new Error("gateway.state_db must be a string when present");
+    }
+    const stateDbPath = resolveStateDbPath(stateDbValue, configPath, env);
+    return {
+        configPath,
+        stateDbPath,
+        mediaRootPath: resolveMediaRootPath(stateDbPath),
+        hasLegacyGatewayTimezone: rawConfig?.gateway?.timezone !== undefined,
+        legacyGatewayTimezone: readLegacyGatewayTimezone(rawConfig?.gateway?.timezone),
+        mailbox: parseMailboxConfig(rawConfig?.gateway?.mailbox),
+        cron: parseCronConfig(rawConfig?.cron),
+        telegram: parseTelegramConfig(rawConfig?.channels?.telegram, env),
+    };
+}
+function parseMailboxConfig(value) {
+    const table = readMailboxTable(value);
+    return {
+        batchReplies: readBoolean(table.batch_replies, "gateway.mailbox.batch_replies", false),
+        batchWindowMs: readBatchWindowMs(table.batch_window_ms),
+        routes: readMailboxRoutes(table.routes),
+    };
+}
+async function readGatewayConfigFile(path) {
+    if (!existsSync(path)) {
+        return null;
+    }
+    const source = await Bun.file(path).text();
+    const parsed = Bun.TOML.parse(source);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`gateway config must decode to a table: ${path}`);
+    }
+    return parsed;
+}
+function resolveStateDbPath(stateDb, configPath, env) {
+    if (!stateDb || stateDb.trim().length === 0) {
+        return defaultStateDbPath(env);
+    }
+    if (isAbsolute(stateDb)) {
+        return stateDb;
+    }
+    return resolve(dirname(configPath), stateDb);
+}
+function readMailboxTable(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("gateway.mailbox must be a table when present");
+    }
+    return value;
+}
+function readBoolean(value, field, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${field} must be a boolean when present`);
+    }
+    return value;
+}
+function readBatchWindowMs(value) {
+    if (value === undefined) {
+        return 1_500;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new Error("gateway.mailbox.batch_window_ms must be an integer when present");
+    }
+    if (value < 0 || value > 60_000) {
+        throw new Error("gateway.mailbox.batch_window_ms must be between 0 and 60000");
+    }
+    return value;
+}
+function readMailboxRoutes(value) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("gateway.mailbox.routes must be an array when present");
+    }
+    const routes = value.map((entry, index) => readMailboxRoute(entry, index));
+    const seen = new Set();
+    for (const route of routes) {
+        const key = `${route.channel}:${route.target}:${route.topic ?? ""}`;
+        if (seen.has(key)) {
+            throw new Error(`gateway.mailbox.routes contains a duplicate match for ${key}`);
+        }
+        seen.add(key);
+    }
+    return routes;
+}
+function readMailboxRoute(value, index) {
+    const field = `gateway.mailbox.routes[${index}]`;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${field} must be a table`);
+    }
+    const route = value;
+    return {
+        channel: readRequiredString(route.channel, `${field}.channel`),
+        target: readRequiredString(route.target, `${field}.target`),
+        topic: readOptionalString(route.topic, `${field}.topic`),
+        mailboxKey: readRequiredString(route.mailbox_key, `${field}.mailbox_key`),
+    };
+}
+function readRequiredString(value, field) {
+    if (typeof value !== "string") {
+        throw new Error(`${field} must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${field} must not be empty`);
+    }
+    return trimmed;
+}
+function readOptionalString(value, field) {
+    if (value === undefined) {
+        return null;
+    }
+    return readRequiredString(value, field);
+}
+function readLegacyGatewayTimezone(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? null : trimmed;
+}
+function defaultStateDbPath(env) {
+    return defaultGatewayStateDbPath(env);
+}
+function resolveMediaRootPath(stateDbPath) {
+    return join(dirname(stateDbPath), "media");
+}

package/dist/config/paths.d.ts

@@ -0,0 +1,10 @@
+export declare const GATEWAY_CONFIG_FILE = "opencode-gateway.toml";
+export declare const OPENCODE_CONFIG_FILE = "opencode.json";
+type EnvSource = Record<string, string | undefined>;
+export declare function resolveGatewayConfigPath(env: EnvSource): string;
+export declare function resolveOpencodeConfigDir(env: EnvSource): string;
+export declare function resolveManagedOpencodeConfigDir(env: EnvSource): string;
+export declare function defaultGatewayStateDbPath(env: EnvSource): string;
+export declare function resolveConfigHome(env: EnvSource): string;
+export declare function resolveDataHome(env: EnvSource): string;
+export {};

package/dist/config/paths.js

@@ -0,0 +1,33 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export const GATEWAY_CONFIG_FILE = "opencode-gateway.toml";
+export const OPENCODE_CONFIG_FILE = "opencode.json";
+export function resolveGatewayConfigPath(env) {
+    const explicit = env.OPENCODE_GATEWAY_CONFIG;
+    if (explicit && explicit.trim().length > 0) {
+        return resolve(explicit);
+    }
+    return join(resolveOpencodeConfigDir(env), GATEWAY_CONFIG_FILE);
+}
+export function resolveOpencodeConfigDir(env) {
+    const explicit = env.OPENCODE_CONFIG_DIR;
+    if (explicit && explicit.trim().length > 0) {
+        return resolve(explicit);
+    }
+    return defaultOpencodeConfigDir(env);
+}
+export function resolveManagedOpencodeConfigDir(env) {
+    return join(resolveConfigHome(env), "opencode-gateway", "opencode");
+}
+export function defaultGatewayStateDbPath(env) {
+    return join(resolveDataHome(env), "opencode-gateway", "state.db");
+}
+export function resolveConfigHome(env) {
+    return env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+}
+export function resolveDataHome(env) {
+    return env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+}
+function defaultOpencodeConfigDir(env) {
+    return join(resolveConfigHome(env), "opencode");
+}

package/dist/config/telegram.d.ts

@@ -0,0 +1,13 @@
+type EnvSource = Record<string, string | undefined>;
+export type TelegramConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    botToken: string;
+    botTokenEnv: string;
+    pollTimeoutSeconds: number;
+    allowedChats: string[];
+    allowedUsers: string[];
+};
+export declare function parseTelegramConfig(value: unknown, env: EnvSource): TelegramConfig;
+export {};

package/dist/config/telegram.js

@@ -0,0 +1,91 @@
+export function parseTelegramConfig(value, env) {
+    const table = readTelegramTable(value);
+    const enabled = readBoolean(table.enabled, "channels.telegram.enabled", false);
+    if (!enabled) {
+        return { enabled: false };
+    }
+    const botTokenEnv = readString(table.bot_token_env, "channels.telegram.bot_token_env", "TELEGRAM_BOT_TOKEN");
+    const pollTimeoutSeconds = readPollTimeoutSeconds(table.poll_timeout_seconds);
+    const allowedChats = readIdentifierList(table.allowed_chats, "channels.telegram.allowed_chats");
+    const allowedUsers = readIdentifierList(table.allowed_users, "channels.telegram.allowed_users");
+    const botToken = env[botTokenEnv]?.trim();
+    if (!botToken) {
+        throw new Error(`Telegram is enabled but ${botTokenEnv} is not set`);
+    }
+    if (allowedChats.length === 0 && allowedUsers.length === 0) {
+        throw new Error("Telegram is enabled but no allowlist entries were configured");
+    }
+    return {
+        enabled: true,
+        botToken,
+        botTokenEnv,
+        pollTimeoutSeconds,
+        allowedChats,
+        allowedUsers,
+    };
+}
+function readTelegramTable(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("channels.telegram must be a table when present");
+    }
+    return value;
+}
+function readBoolean(value, field, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${field} must be a boolean when present`);
+    }
+    return value;
+}
+function readString(value, field, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${field} must be a string when present`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${field} must not be empty`);
+    }
+    return trimmed;
+}
+function readPollTimeoutSeconds(value) {
+    if (value === undefined) {
+        return 25;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new Error("channels.telegram.poll_timeout_seconds must be an integer when present");
+    }
+    if (value < 1 || value > 50) {
+        throw new Error("channels.telegram.poll_timeout_seconds must be between 1 and 50");
+    }
+    return value;
+}
+function readIdentifierList(value, field) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${field} must be an array when present`);
+    }
+    return value.map((entry) => normalizeIdentifier(entry, field));
+}
+function normalizeIdentifier(value, field) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            throw new Error(`${field} entries must not be empty`);
+        }
+        return trimmed;
+    }
+    if (typeof value === "number" && Number.isSafeInteger(value)) {
+        return String(value);
+    }
+    throw new Error(`${field} entries must be strings or safe integers`);
+}