@fargowealth/fargo-ai-cli 1.3.0 → 1.4.1

package/src/website-connector-definition.mjs

@@ -1,339 +1 @@
-const CONNECTOR_ID = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
-const OPERATION_ID = /^[a-z][a-z0-9_]{1,62}[a-z0-9]$/;
-const TEMPLATE_ARGUMENT = /\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g;
-const FORBIDDEN_HEADERS = new Set([
-  "connection",
-  "content-length",
-  "cookie",
-  "host",
-  "proxy-authorization",
-  "transfer-encoding",
-  "upgrade"
-]);
-
-export const WEBSITE_CONNECTOR_SCHEMA_VERSION = "fargo.website-connector/v1";
-
-export class WebsiteConnectorDefinitionError extends Error {
-  constructor(code, path = "") {
-    super(path ? `${code}:${path}` : code);
-    this.name = "WebsiteConnectorDefinitionError";
-    this.code = code;
-    this.path = path;
-  }
-}
-
-export function parseWebsiteConnectorDefinition(value) {
-  const source = record(value, "website_connector_definition_invalid", "/");
-  equal(source.schemaVersion, WEBSITE_CONNECTOR_SCHEMA_VERSION, "website_connector_schema_version_invalid", "/schemaVersion");
-  const connectorId = requiredText(source.connectorId, 64, "website_connector_id_invalid", "/connectorId");
-  if (!CONNECTOR_ID.test(connectorId)) fail("website_connector_id_invalid", "/connectorId");
-  const displayName = requiredText(source.displayName, 120, "website_connector_display_name_invalid", "/displayName");
-  const allowedOrigins = uniqueArray(source.allowedOrigins, 1, 12, "/allowedOrigins").map((origin, index) => (
-    exactHttpsOrigin(origin, "website_connector_origin_invalid", `/allowedOrigins/${index}`)
-  ));
-  const loginUrl = optionalHttpsUrl(source.loginUrl, allowedOrigins, "/loginUrl");
-  const auth = parseAuthRecipe(source.auth, allowedOrigins);
-  if (auth.kind === "browser_storage" && !loginUrl) fail("website_connector_login_url_required", "/loginUrl");
-  const operations = uniqueArray(source.operations, 1, 80, "/operations").map((operation, index) => (
-    parseOperation(operation, allowedOrigins, index)
-  ));
-  const operationIds = new Set();
-  for (const operation of operations) {
-    if (operationIds.has(operation.operationId)) fail("website_operation_id_duplicate", `/operations/${operation.operationId}`);
-    if (operation.requiresConnection && auth.kind !== "browser_storage") {
-      fail("website_operation_connection_auth_required", `/operations/${operation.operationId}/requiresConnection`);
-    }
-    operationIds.add(operation.operationId);
-  }
-  return {
-    schemaVersion: WEBSITE_CONNECTOR_SCHEMA_VERSION,
-    connectorId,
-    displayName,
-    allowedOrigins,
-    ...(loginUrl ? { loginUrl } : {}),
-    auth,
-    operations
-  };
-}
-
-export function connectorToolName(connectorId, operationId) {
-  const left = String(connectorId || "").replaceAll("-", "_");
-  return `${left}_${operationId}`;
-}
-
-export function renderWebsiteOperation(definition, operationId, rawArguments) {
-  const parsed = parseWebsiteConnectorDefinition(definition);
-  const operation = parsed.operations.find((candidate) => candidate.operationId === operationId);
-  if (!operation) fail("website_operation_not_found", "/operationId");
-  const args = record(rawArguments ?? {}, "website_operation_arguments_invalid", "/arguments");
-  validateArguments(args, operation.inputSchema);
-  const path = renderString(operation.request.path, args, "/request/path");
-  const url = new URL(path, `${operation.request.origin}/`);
-  if (url.origin !== operation.request.origin) fail("website_operation_origin_escape", "/request/path");
-  for (const [name, argumentName] of Object.entries(operation.request.query)) {
-    const value = args[argumentName];
-    if (value !== undefined && value !== null) url.searchParams.set(name, scalarText(value, `/arguments/${argumentName}`));
-  }
-  const body = operation.request.body === undefined
-    ? undefined
-    : renderBody(operation.request.body, args, "/request/body");
-  return {
-    definition: parsed,
-    operation,
-    request: {
-      body,
-      headers: { ...operation.request.headers },
-      method: operation.request.method,
-      url: url.toString()
-    }
-  };
-}
-
-function parseAuthRecipe(value, allowedOrigins) {
-  const source = value === undefined ? { kind: "none" } : record(value, "website_auth_recipe_invalid", "/auth");
-  if (source.kind === "none") return { kind: "none" };
-  equal(source.kind, "browser_storage", "website_auth_recipe_invalid", "/auth/kind");
-  const sendCookies = source.sendCookies === true;
-  const headerSources = source.headerSources === undefined
-    ? []
-    : uniqueArray(source.headerSources, 0, 12, "/auth/headerSources").map((item, index) => {
-        const binding = record(item, "website_auth_header_source_invalid", `/auth/headerSources/${index}`);
-        const name = headerName(binding.name, `/auth/headerSources/${index}/name`, true);
-        const origin = exactHttpsOrigin(binding.origin, "website_auth_header_source_invalid", `/auth/headerSources/${index}/origin`);
-        if (!allowedOrigins.includes(origin)) fail("website_auth_origin_not_allowed", `/auth/headerSources/${index}/origin`);
-        const keySuffix = requiredText(binding.keySuffix, 240, "website_auth_header_source_invalid", `/auth/headerSources/${index}/keySuffix`);
-        const prefix = optionalHeaderPrefix(binding.prefix, `/auth/headerSources/${index}/prefix`);
-        return { keySuffix, name, origin, ...(prefix ? { prefix } : {}) };
-      });
-  if (!sendCookies && headerSources.length === 0) fail("website_auth_recipe_empty", "/auth");
-  return { kind: "browser_storage", sendCookies, headerSources };
-}
-
-function parseOperation(value, allowedOrigins, index) {
-  const path = `/operations/${index}`;
-  const source = record(value, "website_operation_invalid", path);
-  const operationId = requiredText(source.operationId, 64, "website_operation_id_invalid", `${path}/operationId`);
-  if (!OPERATION_ID.test(operationId)) fail("website_operation_id_invalid", `${path}/operationId`);
-  const description = requiredText(source.description, 500, "website_operation_description_invalid", `${path}/description`);
-  const readOnly = source.readOnly === true;
-  const requiresConnection = source.requiresConnection === true;
-  const riskLevel = optionalEnum(source.riskLevel, ["low", "medium", "high", "critical"], readOnly ? "low" : "medium", `${path}/riskLevel`);
-  const inputSchema = parseInputSchema(source.inputSchema, `${path}/inputSchema`);
-  const requestSource = record(source.request, "website_operation_request_invalid", `${path}/request`);
-  const origin = exactHttpsOrigin(requestSource.origin, "website_operation_origin_invalid", `${path}/request/origin`);
-  if (!allowedOrigins.includes(origin)) fail("website_operation_origin_not_allowed", `${path}/request/origin`);
-  const method = optionalEnum(requestSource.method, ["GET", "POST", "PUT", "PATCH", "DELETE"], "GET", `${path}/request/method`);
-  if (readOnly && method !== "GET") fail("website_operation_read_only_method_invalid", `${path}/request/method`);
-  const requestPath = requiredText(requestSource.path, 2_000, "website_operation_path_invalid", `${path}/request/path`);
-  if (!requestPath.startsWith("/") || requestPath.startsWith("//") || requestPath.includes("\\")) {
-    fail("website_operation_path_invalid", `${path}/request/path`);
-  }
-  const pathArguments = [...requestPath.matchAll(TEMPLATE_ARGUMENT)].map((match) => match[1]);
-  const properties = record(inputSchema.properties ?? {}, "website_operation_input_schema_invalid", `${path}/inputSchema/properties`);
-  for (const argument of pathArguments) {
-    if (!Object.hasOwn(properties, argument)) fail("website_operation_template_argument_unknown", `${path}/request/path`);
-  }
-  const query = requestSource.query === undefined
-    ? {}
-    : Object.fromEntries(Object.entries(record(requestSource.query, "website_operation_query_invalid", `${path}/request/query`)).map(([name, argument]) => {
-        if (!/^[A-Za-z0-9_.~-]{1,120}$/.test(name)) fail("website_operation_query_name_invalid", `${path}/request/query/${name}`);
-        const argumentName = requiredText(argument, 120, "website_operation_query_argument_invalid", `${path}/request/query/${name}`);
-        if (!Object.hasOwn(properties, argumentName)) fail("website_operation_query_argument_unknown", `${path}/request/query/${name}`);
-        return [name, argumentName];
-      }));
-  const headers = requestSource.headers === undefined
-    ? {}
-    : Object.fromEntries(Object.entries(record(requestSource.headers, "website_operation_headers_invalid", `${path}/request/headers`)).map(([name, headerValue]) => {
-        const normalized = requiredText(headerValue, 500, "website_operation_header_value_invalid", `${path}/request/headers/${name}`);
-        if (/[\r\n\0]/.test(normalized)) fail("website_operation_header_value_invalid", `${path}/request/headers/${name}`);
-        return [headerName(name, `${path}/request/headers/${name}`, false), normalized];
-      }));
-  const body = requestSource.body;
-  if (body !== undefined && method === "GET") fail("website_operation_get_body_invalid", `${path}/request/body`);
-  if (body !== undefined) validateBodyTemplate(body, properties, `${path}/request/body`);
-  return {
-    operationId,
-    description,
-    readOnly,
-    requiresConnection,
-    riskLevel,
-    inputSchema,
-    request: {
-      origin,
-      method,
-      path: requestPath,
-      query,
-      headers,
-      ...(body === undefined ? {} : { body })
-    }
-  };
-}
-
-function optionalHeaderPrefix(value, path) {
-  if (value === undefined || value === null || value === "") return "";
-  if (typeof value !== "string" || value.length > 80 || /[\r\n\0]/.test(value)) {
-    fail("website_auth_header_source_invalid", path);
-  }
-  return value;
-}
-
-function parseInputSchema(value, path) {
-  const source = value === undefined
-    ? { additionalProperties: false, properties: {}, type: "object" }
-    : record(value, "website_operation_input_schema_invalid", path);
-  equal(source.type, "object", "website_operation_input_schema_invalid", `${path}/type`);
-  if (source.additionalProperties !== false) fail("website_operation_input_schema_open", `${path}/additionalProperties`);
-  const properties = record(source.properties ?? {}, "website_operation_input_schema_invalid", `${path}/properties`);
-  const normalizedProperties = {};
-  for (const [name, candidate] of Object.entries(properties)) {
-    if (!/^[A-Za-z][A-Za-z0-9_]{0,119}$/.test(name)) fail("website_operation_input_name_invalid", `${path}/properties/${name}`);
-    const property = record(candidate, "website_operation_input_property_invalid", `${path}/properties/${name}`);
-    const type = optionalEnum(property.type, ["string", "number", "integer", "boolean"], "string", `${path}/properties/${name}/type`);
-    normalizedProperties[name] = {
-      type,
-      ...(typeof property.maxLength === "number" ? { maxLength: boundedInteger(property.maxLength, 1, 20_000, `${path}/properties/${name}/maxLength`) } : {}),
-      ...(Array.isArray(property.enum) ? { enum: property.enum.map((item) => scalar(item, `${path}/properties/${name}/enum`)) } : {})
-    };
-  }
-  const required = source.required === undefined ? [] : uniqueArray(source.required, 0, Object.keys(normalizedProperties).length, `${path}/required`).map(String);
-  for (const name of required) if (!Object.hasOwn(normalizedProperties, name)) fail("website_operation_required_unknown", `${path}/required`);
-  return { additionalProperties: false, properties: normalizedProperties, required, type: "object" };
-}
-
-function validateArguments(args, schema) {
-  for (const required of schema.required) if (!Object.hasOwn(args, required)) fail("website_operation_argument_required", `/arguments/${required}`);
-  for (const [name, value] of Object.entries(args)) {
-    const property = schema.properties[name];
-    if (!property) fail("website_operation_argument_unknown", `/arguments/${name}`);
-    if (property.type === "string" && typeof value !== "string") fail("website_operation_argument_type_invalid", `/arguments/${name}`);
-    if (property.type === "number" && (typeof value !== "number" || !Number.isFinite(value))) fail("website_operation_argument_type_invalid", `/arguments/${name}`);
-    if (property.type === "integer" && !Number.isInteger(value)) fail("website_operation_argument_type_invalid", `/arguments/${name}`);
-    if (property.type === "boolean" && typeof value !== "boolean") fail("website_operation_argument_type_invalid", `/arguments/${name}`);
-    if (property.maxLength && typeof value === "string" && value.length > property.maxLength) fail("website_operation_argument_too_long", `/arguments/${name}`);
-    if (property.enum && !property.enum.some((candidate) => Object.is(candidate, value))) fail("website_operation_argument_enum_invalid", `/arguments/${name}`);
-  }
-}
-
-function validateBodyTemplate(value, properties, path) {
-  if (typeof value === "string") {
-    if (value.startsWith("$") && !Object.hasOwn(properties, value.slice(1))) fail("website_operation_body_argument_unknown", path);
-    return;
-  }
-  if (value === null || typeof value === "number" || typeof value === "boolean") return;
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => validateBodyTemplate(item, properties, `${path}/${index}`));
-    return;
-  }
-  const source = record(value, "website_operation_body_invalid", path);
-  for (const [name, item] of Object.entries(source)) validateBodyTemplate(item, properties, `${path}/${name}`);
-}
-
-function renderBody(value, args, path) {
-  if (typeof value === "string") {
-    if (value.startsWith("$")) return args[value.slice(1)];
-    return renderString(value, args, path);
-  }
-  if (Array.isArray(value)) return value.map((item, index) => renderBody(item, args, `${path}/${index}`));
-  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, renderBody(item, args, `${path}/${name}`)]));
-  return value;
-}
-
-function renderString(value, args, path) {
-  return String(value).replace(TEMPLATE_ARGUMENT, (_match, name) => encodeURIComponent(scalarText(args[name], `/arguments/${name || path}`)));
-}
-
-function scalarText(value, path) {
-  scalar(value, path);
-  return String(value);
-}
-
-function scalar(value, path) {
-  if (!["string", "number", "boolean"].includes(typeof value) || (typeof value === "number" && !Number.isFinite(value))) {
-    fail("website_operation_argument_scalar_required", path);
-  }
-  return value;
-}
-
-function headerName(value, path, allowAuthorization) {
-  const name = requiredText(value, 100, "website_operation_header_name_invalid", path);
-  const normalized = name.toLowerCase();
-  if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(name) || FORBIDDEN_HEADERS.has(normalized) || (!allowAuthorization && normalized === "authorization")) {
-    fail("website_operation_header_name_invalid", path);
-  }
-  return name;
-}
-
-function exactHttpsOrigin(value, code, path) {
-  const text = requiredText(value, 500, code, path);
-  try {
-    const url = new URL(text);
-    if (url.protocol !== "https:" || url.origin !== text || url.username || url.password || !publicHostname(url.hostname)) fail(code, path);
-    return url.origin;
-  } catch (error) {
-    if (error instanceof WebsiteConnectorDefinitionError) throw error;
-    fail(code, path);
-  }
-}
-
-function publicHostname(value) {
-  const hostname = String(value).toLowerCase().replace(/^\[|\]$/g, "");
-  if (!hostname.includes(".") || /^[0-9.]+$/.test(hostname) || hostname.includes(":")) return false;
-  return !hostname.endsWith(".localhost")
-    && !hostname.endsWith(".local")
-    && !hostname.endsWith(".internal")
-    && hostname !== "metadata.google.internal";
-}
-
-function optionalHttpsUrl(value, allowedOrigins, path) {
-  if (value === undefined || value === null || value === "") return undefined;
-  try {
-    const url = new URL(requiredText(value, 2_000, "website_connector_login_url_invalid", path));
-    if (url.protocol !== "https:" || !allowedOrigins.includes(url.origin) || url.username || url.password || url.hash) fail("website_connector_login_url_invalid", path);
-    return url.toString();
-  } catch (error) {
-    if (error instanceof WebsiteConnectorDefinitionError) throw error;
-    fail("website_connector_login_url_invalid", path);
-  }
-}
-
-function record(value, code, path) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) fail(code, path);
-  return value;
-}
-
-function uniqueArray(value, min, max, path) {
-  if (!Array.isArray(value) || value.length < min || value.length > max) fail("website_connector_array_invalid", path);
-  const serialized = value.map((item) => typeof item === "string" ? item : JSON.stringify(item));
-  if (new Set(serialized).size !== serialized.length) fail("website_connector_array_duplicate", path);
-  return value;
-}
-
-function requiredText(value, max, code, path) {
-  const text = typeof value === "string" ? value.trim() : "";
-  if (!text || text.length > max) fail(code, path);
-  return text;
-}
-
-function optionalText(value, max, code, path) {
-  if (value === undefined || value === null || value === "") return undefined;
-  return requiredText(value, max, code, path);
-}
-
-function optionalEnum(value, allowed, fallback, path) {
-  const candidate = value === undefined ? fallback : value;
-  if (!allowed.includes(candidate)) fail("website_connector_enum_invalid", path);
-  return candidate;
-}
-
-function boundedInteger(value, min, max, path) {
-  if (!Number.isInteger(value) || value < min || value > max) fail("website_connector_integer_invalid", path);
-  return value;
-}
-
-function equal(actual, expected, code, path) {
-  if (actual !== expected) fail(code, path);
-}
-
-function fail(code, path) {
-  throw new WebsiteConnectorDefinitionError(code, path);
-}
+export * from "@fargowealth/website-connector-runtime";