bhooai-nexus 0.1.2

package/packages/nexus-email/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@bhooai/nexus-email",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "nodemailer": "^6.9.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "@types/nodemailer": "^6.4.17",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-email/src/EmailService.ts

@@ -0,0 +1,76 @@
+import type { EmailProvider, EmailInput, EmailResult, QueueBackend } from './types.js';
+import { renderTemplate } from './providers.js';
+import { TemplateEngine } from './TemplateEngine.js';
+
+export interface EmailServiceOptions {
+  provider: EmailProvider;
+  templates?: TemplateEngine;
+  /** Optional queue; when set, `queue()` enqueues and a worker drains it. */
+  queue?: QueueBackend;
+  /** Max send attempts per queued job (exponential backoff). */
+  maxAttempts?: number;
+}
+
+/**
+ * EmailService ties a provider + template engine + optional queue together.
+ * `send()` renders (if a template is named) and sends immediately.
+ * `queue()` enqueues for background delivery; `startWorker()` drains the queue
+ * with retries (exponential backoff) until success or max attempts exhausted.
+ */
+export class EmailService {
+  readonly provider: EmailProvider;
+  private readonly templates?: TemplateEngine;
+  private readonly queueBackend?: QueueBackend;
+  private readonly maxAttempts: number;
+  private running = false;
+
+  constructor(opts: EmailServiceOptions) {
+    this.provider = opts.provider;
+    this.templates = opts.templates;
+    this.queueBackend = opts.queue;
+    this.maxAttempts = opts.maxAttempts ?? 3;
+  }
+
+  async send(input: EmailInput): Promise<EmailResult> {
+    const rendered = this.templates ? renderTemplate(input, this.templates) : input;
+    return this.provider.send(rendered);
+  }
+
+  async queue(input: EmailInput): Promise<void> {
+    if (!this.queueBackend) throw new Error('[nexus-email] no queue configured');
+    const rendered = this.templates ? renderTemplate(input, this.templates) : input;
+    await this.queueBackend.push(rendered);
+  }
+
+  /** Start the background worker (idempotent). */
+  startWorker(): void {
+    if (!this.queueBackend || this.running) return;
+    this.running = true;
+    (this.queueBackend as any).subscribe?.((job: EmailInput) => this.processWithRetry(job));
+  }
+
+  /** Process a queued job with exponential backoff up to maxAttempts. */
+  private async processWithRetry(job: EmailInput): Promise<void> {
+    let attempt = 0;
+    let lastErr: unknown;
+    while (attempt < this.maxAttempts) {
+      try {
+        await this.provider.send(job);
+        return;
+      } catch (err) {
+        lastErr = err;
+        attempt++;
+        if (attempt >= this.maxAttempts) break;
+        const backoff = 250 * 2 ** (attempt - 1);
+        await new Promise<void>((r) => setTimeout(r, backoff));
+      }
+    }
+    // Give up; in production this should go to a dead-letter store.
+    console.error(`[nexus-email] delivery failed after ${this.maxAttempts} attempts:`, (lastErr as Error)?.message);
+  }
+
+  async close(): Promise<void> {
+    this.running = false;
+    await this.queueBackend?.close();
+  }
+}

package/packages/nexus-email/src/TemplateEngine.ts

@@ -0,0 +1,62 @@
+/**
+ * Minimal template engine for emails: `{{name}}` interpolation, `{{#if cond}}…{{/if}}`
+ * conditionals (with optional `{{else}}`), and `{{#each items}}…{{this}}…{{/each}}`
+ * iteration over arrays. No external dependency (no Handlebars) — sufficient for
+ * transactional email templates. Each transformation is applied in sequence
+ * (each → if → interpolate); `#each` bodies are rendered recursively per item with
+ * `this` merged into the vars.
+ */
+export class TemplateEngine {
+  private readonly templates = new Map<string, string>();
+
+  register(name: string, body: string): void {
+    this.templates.set(name, body);
+  }
+
+  has(name: string): boolean {
+    return this.templates.has(name);
+  }
+
+  render(name: string, vars: Record<string, unknown> = {}): string {
+    const body = this.templates.get(name);
+    if (body == null) throw new Error(`[nexus-email] unknown template: ${name}`);
+    return this.renderString(body, vars);
+  }
+
+  renderString(tpl: string, vars: Record<string, unknown>): string {
+    return interpolate(expandIf(expandEach(tpl, vars), vars), vars);
+  }
+}
+
+/** Expand `{{#each key}}…{{/each}}` by rendering the body recursively per item. */
+function expandEach(tpl: string, vars: Record<string, unknown>): string {
+  return tpl.replace(/\{\{#each\s+(\w+(?:\.\w+)*)\s*\}\}([\s\S]*?)\{\{\/each\}\}/g, (_m, key: string, body: string) => {
+    const arr = lookup(vars, key.trim());
+    if (!Array.isArray(arr)) return '';
+    return arr.map((item) => interpolate(expandIf(expandEach(body, { ...vars, this: item }), { ...vars, this: item }), { ...vars, this: item })).join('');
+  });
+}
+
+/** Expand `{{#if cond}}…{{else}}…{{/if}}` (cond truthy; empty arrays are falsy). */
+function expandIf(tpl: string, vars: Record<string, unknown>): string {
+  return tpl.replace(/\{\{#if\s+([^}]+?)\s*\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}/g, (_m, cond: string, then: string, els?: string) => {
+    const val = lookup(vars, cond.trim());
+    const truthy = Array.isArray(val) ? val.length > 0 : !!val;
+    return truthy ? then : (els ?? '');
+  });
+}
+
+/** Replace `{{key}}` (and `{{ a.b.c }}`) with values; unknown keys → ''. */
+function interpolate(tpl: string, vars: Record<string, unknown>): string {
+  return tpl.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_m, expr: string) => {
+    const val = lookup(vars, expr.trim());
+    return val == null ? '' : String(val);
+  });
+}
+
+function lookup(vars: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce<unknown>((acc, key) => {
+    if (acc == null || typeof acc !== 'object') return undefined;
+    return (acc as Record<string, unknown>)[key];
+  }, vars);
+}

package/packages/nexus-email/src/index.ts

@@ -0,0 +1,37 @@
+export * from './types.js';
+export * from './TemplateEngine.js';
+export * from './providers.js';
+export * from './queue.js';
+export * from './EmailService.js';
+
+import { SmtpProvider, LogProvider } from './providers.js';
+import { TemplateEngine } from './TemplateEngine.js';
+import { EmailService, type EmailServiceOptions } from './EmailService.js';
+import type { EmailProvider, QueueBackend } from './types.js';
+
+export interface EmailConfigLike {
+  provider: 'smtp' | 'log';
+  smtp?: { host: string; port: number; secure: boolean; user: string; pass: string };
+  from: string;
+}
+
+export interface CreateEmailOptions {
+  /** Inject a custom provider (tests). */
+  provider?: EmailProvider;
+  /** Inject a queue backend (default: none → send is synchronous only). */
+  queue?: QueueBackend;
+  templates?: TemplateEngine;
+  maxAttempts?: number;
+}
+
+/**
+ * Build an EmailService from the `email` config section. `provider: 'log'`
+ * never sends (dev/test); `provider: 'smtp'` uses nodemailer with the smtp config.
+ */
+export function createEmail(config: EmailConfigLike, opts: CreateEmailOptions = {}): EmailService {
+  const provider: EmailProvider = opts.provider
+    ?? (config.provider === 'smtp' && config.smtp
+      ? new SmtpProvider(config.smtp)
+      : new LogProvider());
+  return new EmailService({ provider, templates: opts.templates, queue: opts.queue, maxAttempts: opts.maxAttempts });
+}

package/packages/nexus-email/src/providers.ts

@@ -0,0 +1,63 @@
+import nodemailer, { type Transport } from 'nodemailer';
+import type { EmailProvider, EmailInput, EmailResult } from './types.js';
+import { TemplateEngine } from './TemplateEngine.js';
+
+/** SMTP provider backed by nodemailer. The transport is injectable for tests. */
+export class SmtpProvider implements EmailProvider {
+  readonly name = 'smtp';
+  private readonly transport: { sendMail: (opts: any) => Promise<unknown> };
+
+  constructor(
+    opts: {
+      host: string;
+      port: number;
+      secure: boolean;
+      user: string;
+      pass: string;
+    },
+    /** Inject a custom nodemailer Transport (tests use `jsonTransport`). */
+    customTransport?: Transport,
+  ) {
+    this.transport = customTransport
+      ? nodemailer.createTransport(customTransport as any)
+      : nodemailer.createTransport({ host: opts.host, port: opts.port, secure: opts.secure, auth: { user: opts.user, pass: opts.pass } });
+  }
+
+  async send(input: EmailInput): Promise<EmailResult> {
+    const res = (await this.transport.sendMail({
+      to: input.to,
+      cc: input.cc,
+      bcc: input.bcc,
+      subject: input.subject,
+      html: input.html,
+      text: input.text,
+      attachments: input.attachments,
+      replyTo: input.replyTo,
+      headers: input.headers,
+    })) as { messageId?: string; envelope?: unknown };
+    return { messageId: res.messageId, envelope: res.envelope, raw: res, input };
+  }
+}
+
+/**
+ * Log provider: writes the email to the logger instead of sending it. Used when
+ * `config.email.provider === 'log'` (dev/test) so the app runs without SMTP.
+ */
+export class LogProvider implements EmailProvider {
+  readonly name = 'log';
+  private readonly log: (line: string) => void;
+  constructor(log?: (line: string) => void) {
+    this.log = log ?? ((line) => console.log(`[nexus-email] ${line}`));
+  }
+  async send(input: EmailInput): Promise<EmailResult> {
+    this.log(JSON.stringify({ name: input.to, subject: input.subject, text: input.text ?? input.html }));
+    return { messageId: `log-${Date.now()}`, input };
+  }
+}
+
+/** Render an EmailInput's template (if any) against the provided engine. */
+export function renderTemplate(input: EmailInput, engine: TemplateEngine): EmailInput {
+  if (!input.template) return input;
+  const html = engine.render(input.template, input.vars ?? {});
+  return { ...input, html: input.html ?? html, subject: /\{\{/.test(input.subject) ? engine.renderString(input.subject, input.vars ?? {}) : input.subject };
+}

package/packages/nexus-email/src/queue.ts

@@ -0,0 +1,103 @@
+import type { EmailInput, QueueBackend } from './types.js';
+
+/**
+ * In-memory queue backend: push appends to an array; the consumer drains it on a
+ * poll interval. Sufficient for single-instance apps and tests; RedisQueue is the
+ * horizontal-scale option (below). The queue never blocks the sender.
+ */
+export class MemoryQueue implements QueueBackend {
+  private readonly jobs: EmailInput[] = [];
+  private readonly consumers = new Set<(job: EmailInput) => Promise<void>>();
+  private readonly interval: ReturnType<typeof setInterval>;
+  private closed = false;
+
+  constructor(pollMs = 50) {
+    this.interval = setInterval(() => void this.drain(), pollMs);
+  }
+
+  async push(job: EmailInput): Promise<void> {
+    if (this.closed) throw new Error('[nexus-email] queue closed');
+    this.jobs.push(job);
+  }
+
+  subscribe(consumer: (job: EmailInput) => Promise<void>): void {
+    this.consumers.add(consumer);
+  }
+
+  private async drain(): Promise<void> {
+    while (this.jobs.length > 0 && this.consumers.size > 0) {
+      const job = this.jobs.shift();
+      if (!job) break;
+      for (const c of this.consumers) {
+        await c(job);
+      }
+    }
+  }
+
+  get pending(): number {
+    return this.jobs.length;
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    clearInterval(this.interval);
+  }
+}
+
+/**
+ * Redis-backed queue using LPUSH (producer) + RPOP (consumer poll). Uses a
+ * dedicated redis client (the `redis` package). Jobs are JSON-serialized
+ * EmailInputs. Gracefully degrades to no-op if a client can't connect — callers
+ * that need guaranteed delivery should check connectivity at boot.
+ */
+export class RedisQueue implements QueueBackend {
+  private readonly key: string;
+  private client: any;
+  private connected = false;
+  private readonly consumers = new Set<(job: EmailInput) => Promise<void>>();
+  private interval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private readonly createClient: () => any,
+    key = 'nexus:email:queue',
+    pollMs = 100,
+  ) {
+    this.key = key;
+    this.interval = setInterval(() => void this.drain(), pollMs);
+  }
+
+  async ensureConnected(): Promise<void> {
+    if (this.connected) return;
+    this.client = this.createClient();
+    await this.client.connect();
+    this.connected = true;
+  }
+
+  async push(job: EmailInput): Promise<void> {
+    await this.ensureConnected();
+    await this.client.lPush(this.key, JSON.stringify(job));
+  }
+
+  subscribe(consumer: (job: EmailInput) => Promise<void>): void {
+    this.consumers.add(consumer);
+  }
+
+  private async drain(): Promise<void> {
+    if (!this.connected || this.consumers.size === 0) return;
+    try {
+      while (true) {
+        const raw = (await this.client.rPop(this.key)) as string | null;
+        if (!raw) break;
+        const job = JSON.parse(raw) as EmailInput;
+        for (const c of this.consumers) await c(job);
+      }
+    } catch {
+      // transient redis errors shouldn't kill the poller
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.interval) clearInterval(this.interval);
+    if (this.connected) await this.client?.quit();
+  }
+}

package/packages/nexus-email/src/types.ts

@@ -0,0 +1,49 @@
+/** Email-domain types shared by providers, templates, and the service. */
+
+export interface EmailAttachment {
+  filename: string;
+  content: string | Buffer;
+  contentType?: string;
+  /** Path to a file on disk (alternative to inline `content`). */
+  path?: string;
+}
+
+export interface EmailInput {
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  /** HTML body. */
+  html?: string;
+  /** Plain-text body. */
+  text?: string;
+  /** Named template to render (used by EmailService, not providers directly). */
+  template?: string;
+  /** Variables for the template. */
+  vars?: Record<string, unknown>;
+  attachments?: EmailAttachment[];
+  replyTo?: string;
+  headers?: Record<string, string>;
+}
+
+export interface EmailResult {
+  /** Provider message id. */
+  messageId?: string;
+  /** Provider response envelope (nodemailer). */
+  envelope?: unknown;
+  /** Raw response for debugging. */
+  raw?: unknown;
+  /** The input that was sent (for queue/audit). */
+  input: EmailInput;
+}
+
+export interface EmailProvider {
+  readonly name: string;
+  send(input: EmailInput): Promise<EmailResult>;
+}
+
+/** Generic send-queue backend (memory or Redis). */
+export interface QueueBackend {
+  push(job: EmailInput): Promise<void>;
+  close(): Promise<void>;
+}

package/packages/nexus-graphql/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@bhooai/nexus-graphql",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "@bhooai/nexus-auth": "^0.1.0",
+    "graphql": "^16.9.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-graphql/src/federation/composeSupergraph.ts

@@ -0,0 +1,153 @@
+import { buildSchema, isObjectType, isInterfaceType, type GraphQLSchema, type GraphQLObjectType, type GraphQLInterfaceType } from 'graphql';
+import type { Subgraph } from '../types.js';
+import { parseFederationMetadata, type TypeMeta } from './parseMetadata.js';
+import { buildPublicSchema } from '../gateway/publicSchema.js';
+
+export interface EntitySource {
+  subgraph: string;
+  keyFields: string[];
+}
+export interface RequiresRecord {
+  subgraph: string;
+  requiresFields: string[];
+}
+
+export interface Supergraph {
+  subgraphs: Subgraph[];
+  /** typeName -> fieldName -> owning subgraph name. */
+  ownership: Map<string, Map<string, string>>;
+  /** typeName -> subgraphs that can resolve it via _entities (have @key). */
+  entities: Map<string, EntitySource[]>;
+  /** typeName -> fieldName -> subgraph that @provides the field. */
+  provides: Map<string, Map<string, string>>;
+  /** typeName -> fieldName -> { subgraph, requiresFields }. */
+  requires: Map<string, Map<string, RequiresRecord>>;
+  /** Client-facing merged SDL (no federation directives). */
+  mergedSdl: string;
+  /** Schema built from mergedSdl (for query planning/type lookup only). */
+  schema: GraphQLSchema;
+  /** Per-subgraph public schemas (type info). */
+  subgraphSchemas: Map<string, GraphQLSchema>;
+  /** Per-subgraph federation metadata. */
+  metadata: Map<string, Map<string, TypeMeta>>;
+}
+
+const ROOT_TYPES = ['Query', 'Mutation', 'Subscription'];
+
+/**
+ * Compose multiple subgraphs into a Supergraph: collect field ownership,
+ * entity @key sources, @provides and @requires records, and a merged public SDL.
+ *
+ * Ownership rule (v1): a field is owned by a subgraph if that subgraph's SDL
+ * defines the field on the type and it is NOT `@external`. The first subgraph
+ * to claim a non-external field wins; a conflicting claim by a second subgraph
+ * is recorded as a composition warning (real federation would arbitrate via
+ * `@shareable`/`@override` — out of scope for v1).
+ */
+export function composeSupergraph(subgraphs: Subgraph[]): Supergraph {
+  if (subgraphs.length === 0) throw new Error('[nexus-graphql] composeSupergraph requires subgraphs');
+
+  const ownership = new Map<string, Map<string, string>>();
+  const entities = new Map<string, EntitySource[]>();
+  const provides = new Map<string, Map<string, string>>();
+  const requires = new Map<string, Map<string, RequiresRecord>>();
+  const subgraphSchemas = new Map<string, GraphQLSchema>();
+  const metadata = new Map<string, Map<string, TypeMeta>>();
+  const conflicts: string[] = [];
+
+  for (const sub of subgraphs) {
+    const pub = buildPublicSchema(sub.sdl);
+    subgraphSchemas.set(sub.name, pub);
+    const meta = parseFederationMetadata(sub.sdl);
+    metadata.set(sub.name, meta);
+
+    for (const [typeName, typeMeta] of meta) {
+      // Entity sources: every @key on the type makes the subgraph a resolver.
+      if (typeMeta.keys.length) {
+        const list = entities.get(typeName) ?? [];
+        for (const keyFields of typeMeta.keys) list.push({ subgraph: sub.name, keyFields });
+        entities.set(typeName, list);
+      }
+      for (const [fieldName, fieldMeta] of typeMeta.fields) {
+        if (fieldMeta.external) continue; // resolved elsewhere — not owned here
+        const typeOwn = ownership.get(typeName) ?? new Map<string, string>();
+        if (typeOwn.has(fieldName) && typeOwn.get(fieldName) !== sub.name) {
+          conflicts.push(`${typeName}.${fieldName} claimed by ${typeOwn.get(fieldName)} and ${sub.name} (v1: first wins)`);
+        } else {
+          typeOwn.set(fieldName, sub.name);
+        }
+        ownership.set(typeName, typeOwn);
+        if (fieldMeta.provides) {
+          const tp = provides.get(typeName) ?? new Map<string, string>();
+          tp.set(fieldName, sub.name);
+          provides.set(typeName, tp);
+        }
+        if (fieldMeta.requires) {
+           const tr = requires.get(typeName) ?? new Map<string, RequiresRecord>();
+          tr.set(fieldName, { subgraph: sub.name, requiresFields: fieldMeta.requires });
+          requires.set(typeName, tr);
+        }
+      }
+    }
+  }
+
+  const mergedSdl = mergeSdl(subgraphs, subgraphSchemas, metadata, ownership);
+  const schema = buildSchema(mergedSdl);
+
+  return { subgraphs, ownership, entities, provides, requires, mergedSdl, schema, subgraphSchemas, metadata };
+}
+
+/** Build the merged public SDL from all subgraphs' public types. */
+function mergeSdl(
+  subgraphs: Subgraph[],
+  subgraphSchemas: Map<string, GraphQLSchema>,
+  _metadata: Map<string, Map<string, TypeMeta>>,
+  ownership: Map<string, Map<string, string>>,
+): string {
+  // Collect each type's fields (name -> SDL type string) from the owning subgraph's public schema.
+  const typeFields = new Map<string, Map<string, string>>();
+  const rootFields = new Map<string, Map<string, string>>(); // Query/Mutation/Subscription
+  const kinds = new Map<string, 'type' | 'interface'>();
+
+  for (const sub of subgraphs) {
+    const pub = subgraphSchemas.get(sub.name)!;
+    const typeMap = pub.getTypeMap();
+    for (const [typeName, gqlType] of Object.entries(typeMap)) {
+      if (typeName.startsWith('__') || typeName.startsWith('_')) continue;
+      if (isObjectType(gqlType)) {
+        const isRoot = ROOT_TYPES.includes(typeName);
+        const target = isRoot ? (rootFields.get(typeName) ?? new Map<string, string>()) : (typeFields.get(typeName) ?? new Map<string, string>());
+        kinds.set(typeName, 'type');
+        for (const field of Object.values(gqlType.getFields())) {
+          const owner = ownership.get(typeName)?.get(field.name);
+          // Include the field if this subgraph owns it (or it's a root field here).
+          if (isRoot || owner === sub.name) {
+            target.set(field.name, field.type.toString());
+          }
+        }
+        if (isRoot) rootFields.set(typeName, target); else typeFields.set(typeName, target);
+      } else if (isInterfaceType(gqlType)) {
+        const target = typeFields.get(typeName) ?? new Map<string, string>();
+        kinds.set(typeName, 'interface');
+        for (const field of Object.values(gqlType.getFields())) {
+          if (ownership.get(typeName)?.get(field.name) === sub.name) target.set(field.name, field.type.toString());
+        }
+        typeFields.set(typeName, target);
+      }
+    }
+  }
+
+  const parts: string[] = [];
+  for (const [typeName, fields] of rootFields) {
+    parts.push(`type ${typeName} {\n${fieldLines(fields)}\n}`);
+  }
+  for (const [typeName, fields] of typeFields) {
+    const kind = kinds.get(typeName) ?? 'type';
+    parts.push(`${kind} ${typeName} {\n${fieldLines(fields)}\n}`);
+  }
+  return parts.join('\n\n');
+}
+
+function fieldLines(fields: Map<string, string>): string {
+  return [...fields.entries()].map(([name, type]) => `  ${name}: ${type}`).join('\n');
+}

package/packages/nexus-graphql/src/federation/createFederatedGateway.ts

@@ -0,0 +1,36 @@
+import { parse, type DocumentNode, type ExecutionResult } from 'graphql';
+import type { Subgraph, GraphQLContext, ExecuteParams } from '../types.js';
+import { composeSupergraph, type Supergraph } from './composeSupergraph.js';
+import { executeFederated, planQuery, type FetchPlan } from './executor.js';
+
+export interface FederatedGateway {
+  /** Client-facing merged schema. */
+  schema: Supergraph['schema'];
+  supergraph: Supergraph;
+  subgraphs: Subgraph[];
+  execute(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<ExecutionResult>;
+  /** Inspect the fetch plan for a query (golden tests / debugging). */
+  plan(document: DocumentNode): FetchPlan;
+}
+
+/**
+ * Compose multiple subgraphs into a federated gateway. The gateway exposes the
+ * merged public schema and executes queries via the naive sequential federated
+ * executor (root fetches + iterative entity-join passes). Subscriptions are not
+ * federated in v1 — route them to the owning subgraph's `SubscriptionServer`.
+ */
+export function createFederatedGateway(subgraphs: Subgraph[]): FederatedGateway {
+  const supergraph = composeSupergraph(subgraphs);
+  return {
+    schema: supergraph.schema,
+    supergraph,
+    subgraphs,
+    async execute(params) {
+      const document: DocumentNode = params.document;
+      return executeFederated(supergraph, document, params.variableValues, (params.contextValue as GraphQLContext) ?? {});
+    },
+    plan(document) {
+      return planQuery(supergraph, document);
+    },
+  };
+}