@graphoria/server 0.1.0

package/src/remoteSchemas/index.ts

@@ -0,0 +1,48 @@
+import type { RemoteSchemaConfig } from "../config";
+import type { RemoteSchemaResolved } from "./types";
+
+import { introspectRemoteSchema } from "./introspect";
+import { transformRemoteSchema } from "./transform";
+import { logger } from "../logging";
+
+/**
+ * Resolve a single remote schema: introspect → transform → produce RemoteSchemaResolved
+ */
+export const resolveRemoteSchema = async (
+  config: RemoteSchemaConfig,
+): Promise<RemoteSchemaResolved> => {
+  const schema = await introspectRemoteSchema(config);
+  return transformRemoteSchema(schema, config);
+};
+
+/**
+ * Resolve all enabled remote schemas in parallel.
+ * Returns an array of successfully resolved schemas; logs warnings for failures.
+ */
+export const resolveRemoteSchemas = async (
+  configs: RemoteSchemaConfig[],
+): Promise<RemoteSchemaResolved[]> => {
+  const enabled = configs.filter((c) => c.enabled !== false);
+
+  if (enabled.length === 0) return [];
+
+  const results = await Promise.allSettled(enabled.map((config) => resolveRemoteSchema(config)));
+
+  const resolved: RemoteSchemaResolved[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result.status === "fulfilled") {
+      resolved.push(result.value);
+    } else {
+      logger("remote-schemas").warn(
+        { schema: enabled[i].name, err: result.reason },
+        "failed to introspect remote schema",
+      );
+    }
+  }
+
+  return resolved;
+};
+
+export type { RemoteSchemaResolved } from "./types";

package/src/remoteSchemas/introspect.ts

@@ -0,0 +1,44 @@
+import { buildClientSchema, getIntrospectionQuery } from "graphql";
+
+import type { RemoteSchemaConfig } from "../config";
+import type { GraphQLSchema, IntrospectionQuery } from "graphql";
+
+/**
+ * Send an introspection query to a remote GraphQL endpoint and return the parsed schema.
+ */
+export const introspectRemoteSchema = async (
+  config: RemoteSchemaConfig,
+): Promise<GraphQLSchema> => {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...(config.headers ?? {}),
+  };
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeout ?? 10000);
+
+  try {
+    const response = await fetch(config.url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ query: getIntrospectionQuery() }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Remote schema "${config.name}" introspection failed: HTTP ${response.status}`,
+      );
+    }
+
+    const json = (await response.json()) as { data?: IntrospectionQuery };
+
+    if (!json.data) {
+      throw new Error(`Remote schema "${config.name}" introspection returned no data`);
+    }
+
+    return buildClientSchema(json.data);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};

package/src/remoteSchemas/proxy.ts

@@ -0,0 +1,146 @@
+import type { SelectionAnalysis } from "../analyzeQuery/types";
+import type { RemoteSchemaResolved } from "./types";
+
+/**
+ * Build the sub-query string for a remote field by stripping the prefix from
+ * the field name and type references.
+ */
+const buildRemoteSubQuery = (
+  field: SelectionAnalysis,
+  originalFieldName: string,
+  prefixMap: RemoteSchemaResolved["prefixMap"],
+): string => {
+  const args = buildArgumentsString(field.arguments);
+  const selections = field.selections?.length
+    ? ` { ${buildSelectionsString(field.selections, prefixMap)} }`
+    : "";
+
+  return `${originalFieldName}${args}${selections}`;
+};
+
+/**
+ * Recursively build a selections string, un-prefixing any type references in inline fragments.
+ */
+const buildSelectionsString = (
+  selections: SelectionAnalysis[],
+  prefixMap: RemoteSchemaResolved["prefixMap"],
+): string =>
+  selections
+    .map((sel) => {
+      const subSelections = sel.selections?.length
+        ? ` { ${buildSelectionsString(sel.selections, prefixMap)} }`
+        : "";
+
+      const aliasPrefix = sel.alias ? `${sel.alias}: ` : "";
+      return `${aliasPrefix}${sel.name}${buildArgumentsString(sel.arguments)}${subSelections}`;
+    })
+    .join(" ");
+
+/**
+ * Serialize arguments back to GraphQL argument syntax.
+ */
+const buildArgumentsString = (args: Record<string, unknown> | undefined): string => {
+  if (!args || Object.keys(args).length === 0) return "";
+
+  const parts = Object.entries(args).map(([key, value]) => `${key}: ${serializeValue(value)}`);
+
+  return `(${parts.join(", ")})`;
+};
+
+/**
+ * Serialize a value to GraphQL literal syntax.
+ */
+const serializeValue = (value: unknown): string => {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `[${value.map(serializeValue).join(", ")}]`;
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).map(
+      ([k, v]) => `${k}: ${serializeValue(v)}`,
+    );
+    return `{${entries.join(", ")}}`;
+  }
+  return String(value);
+};
+
+/**
+ * Build headers for the remote request by merging:
+ * 1. Static headers from configuration
+ * 2. Forwarded headers from the client request
+ */
+const buildHeaders = (
+  config: RemoteSchemaResolved["config"],
+  clientRequest?: Request,
+): Record<string, string> => {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...(config.headers ?? {}),
+  };
+
+  if (clientRequest && config.forwardHeaders?.length) {
+    for (const headerName of config.forwardHeaders) {
+      const value = clientRequest.headers.get(headerName);
+      if (value) {
+        headers[headerName] = value;
+      }
+    }
+  }
+
+  return headers;
+};
+
+/**
+ * Execute a proxied GraphQL query/mutation against a remote schema endpoint.
+ */
+export const proxyRemoteField = async (
+  field: SelectionAnalysis,
+  remoteSchema: RemoteSchemaResolved,
+  originalFieldName: string,
+  variables: Record<string, unknown>,
+  operationType: "query" | "mutation",
+  clientRequest?: Request,
+): Promise<unknown> => {
+  const subQuery = buildRemoteSubQuery(field, originalFieldName, remoteSchema.prefixMap);
+
+  const fullQuery = `${operationType} { ${subQuery} }`;
+
+  const headers = buildHeaders(remoteSchema.config, clientRequest);
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), remoteSchema.config.timeout ?? 10000);
+
+  try {
+    const response = await fetch(remoteSchema.config.url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        query: fullQuery,
+        variables,
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Remote schema "${remoteSchema.config.name}" returned HTTP ${response.status}`,
+      );
+    }
+
+    const json = (await response.json()) as {
+      data?: Record<string, unknown>;
+      errors?: Array<{ message: string }>;
+    };
+
+    if (json.errors?.length) {
+      throw new Error(
+        `Remote schema "${remoteSchema.config.name}" error: ${json.errors[0].message}`,
+      );
+    }
+
+    // Extract the result for the original field name
+    return json.data?.[originalFieldName] ?? null;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};

package/src/remoteSchemas/transform.ts

@@ -0,0 +1,210 @@
+import {
+  isEnumType,
+  isInputObjectType,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  isUnionType,
+} from "graphql";
+
+import type { RemoteSchemaConfig } from "../config";
+import type {
+  GraphQLArgument,
+  GraphQLField,
+  GraphQLNamedType,
+  GraphQLSchema,
+  GraphQLType,
+} from "graphql";
+import type { PrefixMap, RemoteSchemaField, RemoteSchemaResolved } from "./types";
+
+// Built-in GraphQL scalar names that must not be prefixed
+const BUILTIN_SCALARS = new Set(["String", "Int", "Float", "Boolean", "ID"]);
+
+// Built-in introspection types
+const INTROSPECTION_TYPES = new Set([
+  "__Schema",
+  "__Type",
+  "__Field",
+  "__InputValue",
+  "__EnumValue",
+  "__Directive",
+  "__DirectiveLocation",
+]);
+
+/**
+ * Determine if a named type should be prefixed
+ */
+const shouldPrefix = (typeName: string): boolean =>
+  !BUILTIN_SCALARS.has(typeName) && !INTROSPECTION_TYPES.has(typeName);
+
+/**
+ * Prefix a type name if it should be prefixed
+ */
+const prefixTypeName = (name: string, prefix: string): string =>
+  shouldPrefix(name) ? `${prefix}${name}` : name;
+
+/**
+ * Convert a GraphQL type reference to SDL string with prefixing
+ */
+const typeToSDL = (type: GraphQLType, prefix: string): string => {
+  if (isNonNullType(type)) {
+    return `${typeToSDL(type.ofType, prefix)}!`;
+  }
+  if (isListType(type)) {
+    return `[${typeToSDL(type.ofType, prefix)}]`;
+  }
+  const named = type as GraphQLNamedType;
+  return prefixTypeName(named.name, prefix);
+};
+
+/**
+ * Convert a GraphQL argument to SDL string
+ */
+const argumentToSDL = (arg: GraphQLArgument, prefix: string): string => {
+  const typeStr = typeToSDL(arg.type, prefix);
+  if (arg.defaultValue !== undefined) {
+    return `${arg.name}: ${typeStr} = ${JSON.stringify(arg.defaultValue)}`;
+  }
+  return `${arg.name}: ${typeStr}`;
+};
+
+/**
+ * Generate SDL for a field's arguments
+ */
+const argsToSDL = (args: readonly GraphQLArgument[], prefix: string): string =>
+  args.length ? `(${args.map((a) => argumentToSDL(a, prefix)).join(", ")})` : "";
+
+/**
+ * Generate SDL for an object type (type or input)
+ */
+const objectTypeToSDL = (type: GraphQLNamedType, prefix: string): string => {
+  if (isInputObjectType(type)) {
+    const fields = Object.values(type.getFields());
+    const fieldLines = fields.map((f) => `  ${f.name}: ${typeToSDL(f.type, prefix)}`).join("\n");
+    return `input ${prefixTypeName(type.name, prefix)} {\n${fieldLines}\n}`;
+  }
+
+  if (isObjectType(type)) {
+    const fields = Object.values(type.getFields());
+    const fieldLines = fields
+      .map((f) => {
+        const args = argsToSDL(f.args, prefix);
+        return `  ${f.name}${args}: ${typeToSDL(f.type, prefix)}`;
+      })
+      .join("\n");
+    return `type ${prefixTypeName(type.name, prefix)} {\n${fieldLines}\n}`;
+  }
+
+  if (isEnumType(type)) {
+    const values = type.getValues();
+    const valueLines = values.map((v) => `  ${v.name}`).join("\n");
+    return `enum ${prefixTypeName(type.name, prefix)} {\n${valueLines}\n}`;
+  }
+
+  if (isUnionType(type)) {
+    const members = type
+      .getTypes()
+      .map((t) => prefixTypeName(t.name, prefix))
+      .join(" | ");
+    return `union ${prefixTypeName(type.name, prefix)} = ${members}`;
+  }
+
+  if (isScalarType(type) && shouldPrefix(type.name)) {
+    return `scalar ${prefixTypeName(type.name, prefix)}`;
+  }
+
+  return "";
+};
+
+/**
+ * Build a RemoteSchemaField from a GraphQL field
+ */
+const buildRemoteField = (
+  field: GraphQLField<unknown, unknown>,
+  prefix: string,
+  kind: "query" | "mutation",
+): RemoteSchemaField => {
+  const args = argsToSDL(field.args, prefix);
+  const returnType = typeToSDL(field.type, prefix);
+  const prefixedName = `${prefix}${field.name}`;
+
+  return {
+    originalName: field.name,
+    prefixedName,
+    sdl: `${prefixedName}${args}: ${returnType}`,
+    kind,
+  };
+};
+
+/**
+ * Collect all named types reachable from the schema (excluding built-ins and introspection types)
+ */
+const collectUserTypes = (schema: GraphQLSchema): GraphQLNamedType[] => {
+  const typeMap = schema.getTypeMap();
+  return Object.values(typeMap).filter(
+    (type) =>
+      shouldPrefix(type.name) &&
+      type.name !== "Query" &&
+      type.name !== "Mutation" &&
+      type.name !== "Subscription",
+  );
+};
+
+/**
+ * Transform a remote GraphQL schema by applying a prefix to all types and fields.
+ * Returns a RemoteSchemaResolved containing the transformed SDL, field mappings, and prefix map.
+ */
+export const transformRemoteSchema = (
+  schema: GraphQLSchema,
+  config: RemoteSchemaConfig,
+): RemoteSchemaResolved => {
+  const prefix = config.prefix ?? `${config.name}_`;
+
+  // Collect all user-defined types
+  const userTypes = collectUserTypes(schema);
+
+  // Build prefix map
+  const prefixMap: PrefixMap = {
+    toOriginal: {},
+    toPrefixed: {},
+  };
+
+  for (const type of userTypes) {
+    const prefixed = prefixTypeName(type.name, prefix);
+    prefixMap.toOriginal[prefixed] = type.name;
+    prefixMap.toPrefixed[type.name] = prefixed;
+  }
+
+  // Generate SDL for all types
+  const typeSDLs = userTypes.map((type) => objectTypeToSDL(type, prefix)).filter(Boolean);
+
+  // Extract query fields
+  const queryType = schema.getQueryType();
+  const queryFields: RemoteSchemaField[] = [];
+  if (queryType) {
+    const fields = queryType.getFields();
+    for (const field of Object.values(fields)) {
+      queryFields.push(buildRemoteField(field, prefix, "query"));
+    }
+  }
+
+  // Extract mutation fields
+  const mutationType = schema.getMutationType();
+  const mutationFields: RemoteSchemaField[] = [];
+  if (mutationType) {
+    const fields = mutationType.getFields();
+    for (const field of Object.values(fields)) {
+      mutationFields.push(buildRemoteField(field, prefix, "mutation"));
+    }
+  }
+
+  return {
+    config,
+    prefix,
+    typeDefsSDL: typeSDLs.join("\n\n"),
+    queryFields,
+    mutationFields,
+    prefixMap,
+  };
+};

package/src/remoteSchemas/types.ts

@@ -0,0 +1,43 @@
+import type { RemoteSchemaConfig } from "../config";
+
+/**
+ * A resolved remote query or mutation field from introspection
+ */
+export type RemoteSchemaField = {
+  /** Original field name (without prefix) */
+  originalName: string;
+  /** Prefixed field name used in the merged schema */
+  prefixedName: string;
+  /** GraphQL SDL for this field (with arguments) in the merged schema */
+  sdl: string;
+  /** Whether this field is a query or mutation */
+  kind: "query" | "mutation";
+};
+
+/**
+ * Mapping from prefixed type name to original type name
+ */
+export type PrefixMap = {
+  /** Map prefixed name → original name */
+  toOriginal: Record<string, string>;
+  /** Map original name → prefixed name */
+  toPrefixed: Record<string, string>;
+};
+
+/**
+ * Fully resolved remote schema after introspection and transformation
+ */
+export type RemoteSchemaResolved = {
+  /** The original configuration */
+  config: RemoteSchemaConfig;
+  /** Effective prefix (with trailing underscore) */
+  prefix: string;
+  /** Transformed SDL type definitions (prefixed types, inputs, enums, etc.) */
+  typeDefsSDL: string;
+  /** Remote query fields (prefixed) */
+  queryFields: RemoteSchemaField[];
+  /** Remote mutation fields (prefixed) */
+  mutationFields: RemoteSchemaField[];
+  /** Type name prefix mapping */
+  prefixMap: PrefixMap;
+};

package/src/singletons/ai.ts

@@ -0,0 +1,91 @@
+import { buildAgentTools, createAgent, type RoleEntities } from "../ai";
+import type { AIConfig } from "../types/zod/ai";
+
+/**
+ * Default system prompt: pins the agent to the list → describe → execute
+ * workflow and forbids fabrication. Overridable via `ai.systemPrompt`.
+ */
+export const DEFAULT_AI_SYSTEM_PROMPT = `You are a database assistant for a Graphoria GraphQL API. Answer the user's question using ONLY the provided tools. Never fabricate, invent, or guess data.
+
+Required workflow (STOP after step 3 — present results immediately):
+1. list_entities — find relevant tables (REQUIRES \`kind\` or \`search\`; search matches names AND descriptions, so try natural-language keywords).
+2. describe_entity — read the table's columns, the aggregateField signature, and the pre-built \`examples\` (list / filter / aggregate). Prefer copying an example over composing a query from scratch.
+3. query_data — run ONE query (pick aggregate OR list, not both). Then STOP and present the answer.
+
+For counts, totals, grouping, breakdowns, or summaries: use query_data with operation "aggregate" and groupBy. Never fetch all rows and count client-side.
+
+Aggregate shape (\`key\` is an object and must be sub-selected):
+
+  query {
+    <entity>_aggregate(groupBy: [<col>]) {
+      key { <col> }
+      count
+      items { <fields> }
+    }
+  }
+
+CRITICAL: After query_data returns data, present the answer IMMEDIATELY. Do NOT call more tools. Do NOT re-query with a different operation. One query → present results → done. Use a Markdown table for grouped results.`;
+
+export const DEFAULT_AI_PROMPT_TEMPLATE = `Database-query request from the user:
+
+> {prompt}
+
+You MUST follow this EXACT workflow — do NOT skip steps, do NOT answer before completing all steps:
+
+STEP 1 — list_entities: Call with \`kind\` and/or \`search\` to find relevant tables. The result includes a \`name\` field (e.g. "pg_public_contacts"). MEMORIZE the \`tableName\` field (e.g. "contacts") — you will need it for step 3.
+
+STEP 2 — describe_entity: Call using the EXACT \`name\` string from step 1 (do NOT shorten, transform, or guess it — "pg_public_contacts" is NOT "contacts"). The result contains the table's columns — copy the column names EXACTLY for step 3.
+
+STEP 3 — query_data: Send a structured JSON query. Pick ONE operation — aggregate (for grouping/counts) OR list (for row data). Do NOT call both. The entity must be the EXACT resolverName from step 1 (e.g. "pg_public_contacts"). For aggregates, use operation "aggregate" with groupBy. ALWAYS include \`"filters": { "deleted_at": { "is_null": true } }\` unless the user asks for deleted data.
+
+STEP 4 — STOP AND PRESENT: After query_data returns, present the answer IMMEDIATELY. Do NOT call more tools. Do NOT re-query. Format grouped results as a Markdown table. You are DONE after this step.
+
+CRITICAL RULES:
+- NEVER fabricate, invent, or guess query results. ONLY report data returned by query_data.
+- After getting data, STOP. Do not query again. One query_data call is enough.
+- Copy column names EXACTLY from describe_entity — do not guess or invent field names.
+- For aggregates: set \`"operation": "aggregate"\`, provide \`"groupBy"\` as an array of column names.
+- For lists: set \`"operation": "list"\`, provide \`"columns"\` as an array of column names.
+- The \`entity\` field is the EXACT resolverName from step 1 (e.g. "pg_public_contacts", NOT "contacts").
+- Filter operators: eq, neq, like, ilike, gt, gte, lt, lte, is_null. Use \`{ "is_null": true }\` for NULL checks.
+- If you are unsure about ANYTHING, call a tool. Do not guess.`;
+
+let agent: ((prompt: string) => Promise<string>) | null = null;
+
+/**
+ * Build and store the agent, bound to the given role's schema (the agent's
+ * tools see exactly what that role can see). Called at boot when `ai.enabled`.
+ *
+ * Precedence for systemPrompt / promptTemplate:
+ *   1. Env-var override (`AI_SYSTEM_PROMPT` / `AI_PROMPT_TEMPLATE`)
+ *   2. Config-file value (`ai.systemPrompt`)
+ *   3. Built-in default
+ */
+export const instantiateAI = (
+  aiConfig: AIConfig,
+  role: RoleEntities,
+  envOverrides?: { systemPrompt?: string; promptTemplate?: string },
+): void => {
+  const systemPrompt =
+    envOverrides?.systemPrompt ?? aiConfig.systemPrompt ?? DEFAULT_AI_SYSTEM_PROMPT;
+  const template = envOverrides?.promptTemplate ?? DEFAULT_AI_PROMPT_TEMPLATE;
+
+  const tools = buildAgentTools(role);
+  agent = createAgent({
+    tools,
+    systemPrompt,
+    wrap: (prompt: string) => template.replaceAll("{prompt}", prompt),
+  });
+};
+
+export const getAgent = (): ((prompt: string) => Promise<string>) => {
+  if (!agent) {
+    throw new Error("AI agent is not enabled. Set `ai.enabled = true` in your configuration.");
+  }
+  return agent;
+};
+
+/** Test-only reset. */
+export const resetAI = (): void => {
+  agent = null;
+};

package/src/singletons/authentication.ts

@@ -0,0 +1,13 @@
+import type { TokenService } from "../authentication/types";
+
+import { createJWTService } from "../authentication/jwt";
+import { env } from "./env";
+
+// Default to JWT; overridden after configuration is parsed via setTokenService()
+let tokenService: TokenService = createJWTService(env);
+
+export const getTokenService = (): TokenService => tokenService;
+
+export const setTokenService = (service: TokenService): void => {
+  tokenService = service;
+};

package/src/singletons/cache/index.ts

@@ -0,0 +1,4 @@
+export type { CacheStore } from "./types";
+export { LruCacheStore } from "./lruCacheStore";
+export { RedisCacheStore } from "./redisCacheStore";
+export { InvalidationHelper, getCache, registerCache } from "./registry";

package/src/singletons/cache/lruCacheStore.ts

@@ -0,0 +1,34 @@
+import { LRUCache } from "lru-cache";
+
+import type { CacheStore } from "./types";
+
+// oxlint-disable-next-line typescript/no-explicit-any
+export class LruCacheStore implements CacheStore {
+  // oxlint-disable-next-line typescript/no-explicit-any
+  private cache: LRUCache<string, any>;
+
+  // oxlint-disable-next-line typescript/no-explicit-any
+  constructor(options: LRUCache.Options<string, any, unknown>) {
+    this.cache = new LRUCache(options);
+  }
+
+  async get(key: string): Promise<unknown | undefined> {
+    return this.cache.get(key);
+  }
+
+  async set(key: string, value: unknown): Promise<void> {
+    this.cache.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.cache.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+  }
+
+  async keys(): Promise<string[]> {
+    return [...this.cache.keys()];
+  }
+}