bhooai-nexus 0.1.2

package/packages/nexus-graphql/src/subgraph/defineSubgraph.ts

@@ -0,0 +1,115 @@
+import { buildSchema, parse, validate, GraphQLSchema } from 'graphql';
+import type { DefineSubgraphOptions, Subgraph, Resolvers, GraphQLContext, EntityRepresentation, EntityResolver } from '../types.js';
+import { FEDERATION_DIRECTIVE_SDL, FEDERATION_LINK, FEDERATION_TYPES, entityUnionSdl } from './federationDirectives.js';
+import { parseEntityKeys } from './parseKeys.js';
+import { createFieldResolver } from '../gateway/fieldResolver.js';
+
+const DEFAULT_ENTITY_RESOLVER: EntityResolver = (rep) => rep;
+
+/**
+ * Define a federation-compliant subgraph from user typeDefs + resolvers.
+ *
+ * The user SDL may use federation directives (`@key`, `@external`, `@requires`,
+ * `@provides`, `@extends`). We prepend the directive definitions + the `@link`
+ * clause and append the federation boilerplate (`_Any`, `_Entity`, `_Service`,
+ * `Query._service`, `Query._entities`) so the resulting schema is a valid
+ * subgraph: `_service.sdl` returns the subgraph SDL and `_entities` resolves
+ * representations via the provided `entityResolver` (default: pass-through).
+ *
+ * `defineSubgraph` does NOT compose — it produces a single executable subgraph.
+ * The gateway (`createGateway`) executes it in-process for the single-subgraph
+ * case; Phase 6 composes multiple subgraphs.
+ */
+export function defineSubgraph(options: DefineSubgraphOptions): Subgraph {
+  const { name, typeDefs, resolvers = {}, entityResolver = DEFAULT_ENTITY_RESOLVER } = options;
+
+  const entityKeys = parseEntityKeys(typeDefs);
+  const entityUnion = entityUnionSdl([...entityKeys.keys()]);
+
+  // Subgraph SDL = what _service.sdl returns: the user SDL + the @link clause.
+  // (We keep the federation directives in the published SDL — that's the point.)
+  const sdl = `${FEDERATION_LINK}\n\n${typeDefs.trim()}\n`;
+
+  // Executable schema: directive defs + @link + user SDL + federation types + _Entity union.
+  const fullSdl = [
+    FEDERATION_DIRECTIVE_SDL,
+    FEDERATION_LINK,
+    typeDefs,
+    FEDERATION_TYPES,
+    entityUnion,
+  ].join('\n\n');
+
+  let schema: GraphQLSchema;
+  try {
+    schema = buildSchema(fullSdl, { assumeValid: false });
+  } catch (err) {
+    throw new Error(`[nexus-graphql] Failed to build subgraph schema for "${name}": ${(err as Error).message}`);
+  }
+
+  // The `_Entity` union needs a resolveType so graphql-js can pick the concrete
+  // member type for each resolved entity. Entities carry `__typename` from
+  // their representation; we also backfill it onto results that lack it.
+  const entityType = schema.getType('_Entity') as
+    | { resolveType?: (value: any) => string | null }
+    | undefined;
+  if (entityType && 'resolveType' in entityType) {
+    entityType.resolveType = (value: any) => (value && typeof value === 'object' ? (value as any).__typename ?? null : null);
+  }
+
+  // Auto-wire the federation fields into the resolver map (merged, not mutated).
+  const federationResolvers: Resolvers = {
+    ...resolvers,
+    _Any: {
+      // Custom scalar: pass-through serialize/parse.
+      __serialize: (value: unknown) => value,
+      __parseValue: (value: unknown) => value,
+      __parseLiteral: (value: unknown) => value,
+    } as unknown as Resolvers['_Any'],
+    Query: {
+      ...(resolvers.Query ?? {}),
+      _service: () => ({ sdl }),
+      _entities: (_parent: unknown, args: Record<string, any>, ctx: GraphQLContext) =>
+        Promise.all(((args.representations as EntityRepresentation[] | undefined) ?? []).map(async (rep) => {
+          const resolved = await entityResolver(rep, ctx);
+          if (resolved && typeof resolved === 'object' && !('__typename' in resolved)) {
+            (resolved as Record<string, unknown>).__typename = rep.__typename;
+          }
+          return resolved;
+        })),
+    },
+    _Service: {
+      sdl: (parent: { sdl?: string }) => parent.sdl ?? sdl,
+    },
+  };
+
+  // Validate the SDL parses + that the federation directives are used correctly
+  // (e.g. @key has a `fields` arg). buildSchema already enforces directive
+  // argument types/locations; we additionally assert the SDL parses standalone.
+  parse(sdl);
+
+  return {
+    name,
+    schema,
+    sdl,
+    entityKeys,
+    resolvers: federationResolvers,
+    entityResolver,
+  };
+}
+
+/**
+ * Validate a query against a schema before execution (returns errors array).
+ * Useful for the HTTP handler to reject malformed operations early.
+ */
+export function validateOperation(schema: GraphQLSchema, source: string) {
+  let doc;
+  try {
+    doc = parse(source);
+  } catch (err) {
+    return [(err as Error).message];
+  }
+  return validate(schema, doc).map((e) => e.message);
+}
+
+/** Re-export for the gateway to share the resolver wiring. */
+export { createFieldResolver };

package/packages/nexus-graphql/src/subgraph/federationDirectives.ts

@@ -0,0 +1,47 @@
+/**
+ * Federation directive definitions and the `@link` schema directive.
+ *
+ * These are prepended to the user's typeDefs so `buildSchema` accepts the
+ * federation directives (`@key`, `@external`, `@requires`, `@provides`,
+ * `@extends`). We target a Federation v2-style subset (the same directives
+ * Apollo uses); composition (Phase 6) is ours, but the directive *surface*
+ * matches the spec so subgraph SDL is interoperable.
+ *
+ * NOTE: `@link` is declared so `extend schema @link(...)` parses. We do not
+ * enforce the import list — the directives are always declared and available.
+ */
+export const FEDERATION_DIRECTIVE_SDL = /* graphql */ `
+  directive @link(url: String!, import: [String!]) on SCHEMA
+  directive @key(fields: String!) repeatable on OBJECT | INTERFACE
+  directive @external on FIELD_DEFINITION
+  directive @requires(fields: String!) on FIELD_DEFINITION
+  directive @provides(fields: String!) on FIELD_DEFINITION
+  directive @extends on OBJECT | INTERFACE | FIELD_DEFINITION
+`;
+
+/** The `extend schema @link(...)` clause advertising the federation import. */
+export const FEDERATION_LINK = /* graphql */ `
+  extend schema @link(
+    url: "https://specs.apollo.dev/federation/v2.0"
+    import: ["@key", "@external", "@requires", "@provides", "@extends"]
+  )
+`;
+
+/** Federation boilerplate types prepended/appended to make a schema subgraph-compliant. */
+export const FEDERATION_TYPES = /* graphql */ `
+  scalar _Any
+  type _Service { sdl: String! }
+  extend type Query {
+    _service: _Service!
+    _entities(representations: [_Any!]!): [_Entity]!
+  }
+`;
+
+/** Build the `_Entity` union SDL for the given entity type names (or a scalar if none). */
+export function entityUnionSdl(entityTypeNames: string[]): string {
+  if (entityTypeNames.length === 0) return `scalar _Entity`;
+  return `union _Entity = ${entityTypeNames.join(' | ')}`;
+}
+
+/** Names of the federation directives we recognize (for stripping when building the public schema). */
+export const FEDERATION_DIRECTIVE_NAMES = ['key', 'external', 'requires', 'provides', 'extends', 'link'];

package/packages/nexus-graphql/src/subgraph/parseKeys.ts

@@ -0,0 +1,25 @@
+/**
+ * Parse `@key(fields: "...")` directives from subgraph SDL to learn which types
+ * are entities and what their key field paths are. This is a pragmatic regex scan
+ * (not a full SDL parser) — sufficient for the v1 federation subset and for the
+ * composition step in Phase 6. Composite keys like `@key(fields: "id tenant")` are
+ * supported (space-separated, as in the spec).
+ */
+export function parseEntityKeys(typeDefs: string): Map<string, string[]> {
+  const keys = new Map<string, string[]>();
+  // Match `type X ... {` or `extend type X ... {` (and interfaces) up to the body.
+  const typeHeader = /(?:extend\s+)?(?:type|interface)\s+(\w+)([^{]*)\{/g;
+  let m: RegExpExecArray | null;
+  while ((m = typeHeader.exec(typeDefs)) !== null) {
+    const name = m[1]!;
+    const header = m[2]!;
+    const keyFields: string[] = [];
+    const keyRe = /@key\s*\(\s*fields:\s*"([^"]+)"\s*\)/g;
+    let k: RegExpExecArray | null;
+    while ((k = keyRe.exec(header)) !== null) {
+      keyFields.push(...k[1]!.split(/\s+/).filter(Boolean));
+    }
+    if (keyFields.length) keys.set(name, keyFields);
+  }
+  return keys;
+}

package/packages/nexus-graphql/src/subscriptions/PubSub.ts

@@ -0,0 +1,64 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Minimal in-process PubSub for GraphQL subscriptions. Sufficient for the
+ * single-instance default app; a Redis-backed pub/sub adapter can be plugged in
+ * later for cross-instance fanout (mirrors the realtime adapter pattern).
+ *
+ * Usage in a subscription resolver:
+ *   Subscription: {
+ *     messageAdded: {
+ *       subscribe: () => pubsub.asyncIterator('MESSAGE_ADDED'),
+ *       resolve: (payload) => payload,
+ *     }
+ *   }
+ */
+export class PubSub {
+  private ee = new EventEmitter();
+
+  constructor() {
+    this.ee.setMaxListeners(0);
+  }
+
+  /** Publish a payload to a topic. */
+  publish(topic: string, payload: unknown): void {
+    this.ee.emit(topic, payload);
+  }
+
+  /** Return an AsyncIterable that yields payloads published to the topic(s). */
+  asyncIterator(topics: string | string[]): AsyncIterable<any> {
+    const list = Array.isArray(topics) ? topics : [topics];
+    const ee = this.ee;
+    const queue: any[] = [];
+    let pull: ((v: IteratorResult<any>) => void) | undefined;
+
+    for (const t of list) {
+      const push = (payload: any) => {
+        if (pull) {
+          const resolve = pull;
+          pull = undefined;
+          resolve({ value: payload, done: false });
+        } else {
+          queue.push(payload);
+        }
+      };
+      ee.on(t, push);
+    }
+
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          next(): Promise<IteratorResult<any>> {
+            if (queue.length) return Promise.resolve({ value: queue.shift(), done: false });
+            return new Promise((resolve) => { pull = resolve; });
+          },
+          return(): Promise<IteratorResult<any>> {
+            // Unsubscribe listeners on early completion (client disconnect).
+            for (const t of list) ee.removeAllListeners(t);
+            return Promise.resolve({ value: undefined, done: true });
+          },
+        };
+      },
+    };
+  }
+}

package/packages/nexus-graphql/src/subscriptions/SubscriptionServer.ts

@@ -0,0 +1,203 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { parse, validate } from 'graphql';
+import type { AuthService } from '@bhooai/nexus-auth';
+import type { Gateway, GraphQLContext } from '../types.js';
+
+export interface SubscriptionServerOptions {
+  httpServer: HttpServer;
+  gateway: Gateway;
+  /** WS path (default '/graphql/ws'). */
+  path?: string;
+  /** Optional auth: verifies access token from connection_init payload.token or ?token=. */
+  authService?: AuthService;
+  /** Build per-connection resolver context. Default: `{ user }` from auth. */
+  context?: (init: Record<string, unknown> | undefined, user: GraphQLContext['user']) => GraphQLContext | Promise<GraphQLContext>;
+  /** Reject unauthenticated connections (default true when authService provided). */
+  requireAuth?: boolean;
+}
+
+type ClientMsg =
+  | { type: 'connection_init'; payload?: Record<string, unknown> }
+  | { type: 'subscribe'; id: string; payload: { query: string; variables?: Record<string, any>; operationName?: string } }
+  | { type: 'complete'; id: string }
+  | { type: 'ping' }
+  | { type: 'pong' };
+
+interface ActiveSub {
+  iterator: AsyncIterator<unknown>;
+  done: boolean;
+}
+
+const PROTOCOL = 'graphql-transport-ws';
+
+/**
+ * GraphQL subscriptions over WebSocket (the `graphql-transport-ws` protocol).
+ * Attaches to an HTTP server's 'upgrade' event. On `connection_init` we
+ * (optionally) authenticate; on `subscribe` we run the gateway's `subscribe()`
+ * and stream each `next` result back until the client sends `complete` or the
+ * socket closes.
+ */
+export class SubscriptionServer {
+  private wss: WebSocketServer;
+  private opts: SubscriptionServerOptions;
+
+  constructor(opts: SubscriptionServerOptions) {
+    this.opts = opts;
+    this.wss = new WebSocketServer({ noServer: true });
+    this.opts.httpServer.on('upgrade', (req, socket, head) => this.handleUpgrade(req, socket, head));
+  }
+
+  private async handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): Promise<void> {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname !== (this.opts.path ?? '/graphql/ws')) return;
+
+    const protocols = (req.headers['sec-websocket-protocol'] ?? '').toString().split(',').map((s) => s.trim());
+    if (!protocols.includes(PROTOCOL)) {
+      socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+
+    this.wss.handleUpgrade(req, socket, head, (ws) => {
+      this.handleConnection(ws, url);
+    });
+  }
+
+  private async handleConnection(ws: WebSocket, url: URL): Promise<void> {
+    let user: GraphQLContext['user'];
+    let acknowledged = false;
+    const active = new Map<string, ActiveSub>();
+
+    const send = (msg: unknown) => { if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg)); };
+
+    const cleanup = async () => {
+      for (const [, sub] of active) {
+        if (!sub.done) { sub.done = true; try { await sub.iterator.return?.(); } catch { /* ignore */ } }
+      }
+      active.clear();
+    };
+
+    // If auth is required and no token is supplied via ?token=, we can reject
+    // early; but the protocol sends the token in connection_init, so we wait.
+    ws.on('message', async (data) => {
+      let msg: ClientMsg;
+      try { msg = JSON.parse(data.toString('utf8')) as ClientMsg; } catch { return; }
+
+      switch (msg.type) {
+        case 'connection_init': {
+          try {
+            user = await this.authenticate(msg.payload, url);
+          } catch (err) {
+            send({ type: 'error', id: '', payload: [{ message: (err as Error).message }] });
+            ws.close(4401, 'Unauthorized');
+            return;
+          }
+          acknowledged = true;
+          send({ type: 'connection_ack' });
+          return;
+        }
+        case 'ping':
+          send({ type: 'pong' });
+          return;
+        case 'pong':
+          return;
+        case 'subscribe': {
+          if (!acknowledged) { send({ type: 'error', id: msg.id, payload: [{ message: 'connection not acknowledged' }] }); return; }
+          await this.runSubscription(msg, ws, active, user);
+          return;
+        }
+        case 'complete': {
+          const sub = active.get(msg.id);
+          if (sub && !sub.done) { sub.done = true; try { await sub.iterator.return?.(); } catch { /* ignore */ } }
+          active.delete(msg.id);
+          return;
+        }
+      }
+    });
+
+    ws.on('close', () => void cleanup());
+    ws.on('error', () => void cleanup());
+  }
+
+  private async authenticate(payload: Record<string, unknown> | undefined, url: URL): Promise<GraphQLContext['user']> {
+    const requireAuth = this.opts.requireAuth ?? !!this.opts.authService;
+    if (!this.opts.authService) {
+      if (requireAuth) throw new Error('Authentication required but no authService configured');
+      return undefined;
+    }
+    const token = (payload?.token as string | undefined) ?? url.searchParams.get('token');
+    if (!token) {
+      if (requireAuth) throw new Error('Missing access token');
+      return undefined;
+    }
+    const claims = await this.opts.authService.verifyAccessToken(token);
+    return { sub: claims.sub, roles: claims.roles ?? [], sid: claims.sid };
+  }
+
+  private async runSubscription(
+    msg: { type: 'subscribe'; id: string; payload: { query: string; variables?: Record<string, any>; operationName?: string } },
+    ws: WebSocket,
+    active: Map<string, ActiveSub>,
+    user: GraphQLContext['user'],
+  ): Promise<void> {
+    const send = (m: unknown) => { if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(m)); };
+
+    let document;
+    try {
+      document = parse(msg.payload.query);
+    } catch (err) {
+      send({ type: 'error', id: msg.id, payload: [{ message: (err as Error).message }] });
+      return;
+    }
+
+    const errors = validate(this.opts.gateway.schema, document);
+    if (errors.length) {
+      send({ type: 'error', id: msg.id, payload: errors.map((e) => ({ message: e.message })) });
+      return;
+    }
+
+    const contextValue = this.opts.context
+      ? await this.opts.context(undefined, user)
+      : { user };
+
+    let stream;
+    try {
+      stream = await this.opts.gateway.subscribe({
+        document,
+        variableValues: msg.payload.variables,
+        operationName: msg.payload.operationName,
+        contextValue,
+      });
+    } catch (err) {
+      send({ type: 'error', id: msg.id, payload: [{ message: (err as Error).message }] });
+      return;
+    }
+
+    const sub: ActiveSub = { iterator: stream[Symbol.asyncIterator](), done: false };
+    active.set(msg.id, sub);
+
+    // Pump results asynchronously; stop when the client completes or the stream ends.
+    void (async () => {
+      try {
+        while (!sub.done) {
+          const { value, done } = await sub.iterator.next();
+          if (done) break;
+          if (ws.readyState !== ws.OPEN) break;
+          send({ type: 'next', id: msg.id, payload: value });
+        }
+        if (!sub.done && ws.readyState === ws.OPEN) send({ type: 'complete', id: msg.id });
+      } catch (err) {
+        send({ type: 'error', id: msg.id, payload: [{ message: (err as Error).message }] });
+      } finally {
+        active.delete(msg.id);
+      }
+    })();
+  }
+
+  close(): Promise<void> {
+    this.wss.close();
+    return Promise.resolve();
+  }
+}

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

@@ -0,0 +1,77 @@
+import type { GraphQLSchema, ExecutionResult, DocumentNode } from 'graphql';
+
+/** A field resolver: (parent, args, context, info) => value | Promise<value>. */
+export type Resolver = (parent: any, args: Record<string, any>, context: GraphQLContext, info: any) => any | Promise<any>;
+
+/** A subscribe resolver returning an AsyncIterable of event payloads. */
+export type SubscribeResolver = (parent: any, args: Record<string, any>, context: GraphQLContext, info: any) => AsyncIterable<any> | Promise<AsyncIterable<any>>;
+
+/** Resolvers for a type. Fields may have a plain resolver or `{ resolve, subscribe }` (subscriptions). */
+export type TypeResolvers = Record<string, Resolver | { resolve?: Resolver; subscribe?: SubscribeResolver }>;
+
+export interface Resolvers {
+  [typeName: string]: TypeResolvers;
+}
+
+/** Per-request context passed to every resolver. */
+export interface GraphQLContext {
+  /** The raw HTTP/WS request (for auth headers, ip, etc.). */
+  request?: unknown;
+  /** Authenticated user payload (sub, roles, sid) when auth is applied. */
+  user?: { sub: string; roles: string[]; sid?: string };
+  /** Anything the host wants to inject (DB connections, services, dataloaders). */
+  [key: string]: unknown;
+}
+
+/** Entity representation: `__typename` + the key fields of an entity. */
+export interface EntityRepresentation {
+  __typename: string;
+  [key: string]: unknown;
+}
+
+/** Resolves an entity by its representation. Returns the object (with fields) or null. */
+export type EntityResolver = (representation: EntityRepresentation, context: GraphQLContext) => Promise<any | null> | any | null;
+
+export interface DefineSubgraphOptions {
+  /** Subgraph name (used as the `__typename` source id and in composition). */
+  name: string;
+  /** The subgraph SDL (user types + federation directives like `@key`). */
+  typeDefs: string;
+  /** Field resolvers. */
+  resolvers?: Resolvers;
+  /** Entity resolver for `_entities`. Defaults to returning the representation as-is. */
+  entityResolver?: EntityResolver;
+}
+
+/** A built subgraph, ready to be composed or executed in-process. */
+export interface Subgraph {
+  name: string;
+  /** Executable schema including federation boilerplate (_service, _entities). */
+  schema: GraphQLSchema;
+  /** The subgraph SDL (with federation directives) — what `_service.sdl` returns. */
+  sdl: string;
+  /** Map of entity typeName -> key field paths (e.g. `["id"]` or `["id email"]`). */
+  entityKeys: Map<string, string[]>;
+  resolvers: Resolvers;
+  entityResolver: EntityResolver;
+}
+
+export interface ExecuteParams {
+  schema: GraphQLSchema;
+  document: DocumentNode;
+  resolvers: Resolvers;
+  variableValues?: Record<string, any>;
+  operationName?: string;
+  contextValue?: GraphQLContext;
+  rootValue?: any;
+}
+
+export type ExecutionResultLike = ExecutionResult;
+
+export interface Gateway {
+  /** Public (client-facing) schema — federation internals stripped. */
+  schema: GraphQLSchema;
+  subgraphs: Subgraph[];
+  execute(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<ExecutionResult>;
+  subscribe(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<AsyncIterable<ExecutionResult>>;
+}

package/packages/nexus-payments/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@bhooai/nexus-payments",
+  "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"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-payments/src/errors.ts

@@ -0,0 +1,15 @@
+/** Payment-domain error. `code` is machine-readable; `provider` names the gateway. */
+export class PaymentError extends Error {
+  readonly code: string;
+  readonly provider: string;
+  readonly status?: number;
+  readonly raw?: unknown;
+  constructor(message: string, opts: { code: string; provider: string; status?: number; raw?: unknown }) {
+    super(message);
+    this.name = 'PaymentError';
+    this.code = opts.code;
+    this.provider = opts.provider;
+    this.status = opts.status;
+    this.raw = opts.raw;
+  }
+}

package/packages/nexus-payments/src/http.ts

@@ -0,0 +1,53 @@
+import type { HttpTransport, HttpRequest, HttpResponse } from './types.js';
+import { PaymentError } from './errors.js';
+
+/**
+ * Default HTTP transport built on the global `fetch` (Node >= 18). Providers
+ * accept any `HttpTransport`, so tests inject a mock and never touch the network.
+ */
+export const fetchTransport: HttpTransport = async (req: HttpRequest): Promise<HttpResponse> => {
+  const res = await fetch(req.url, {
+    method: req.method,
+    headers: req.headers,
+    body: req.body,
+  });
+  const text = await res.text();
+  const headers: Record<string, string> = {};
+  res.headers.forEach((v, k) => {
+    headers[k] = v;
+  });
+  return { status: res.status, body: text, headers };
+};
+
+/** Run a JSON request through `transport`, parse JSON, and throw PaymentError on non-2xx. */
+export async function jsonRequest(
+  transport: HttpTransport,
+  provider: string,
+  req: HttpRequest,
+): Promise<any> {
+  const res = await transport(req);
+  const parsed = safeJson(res.body);
+  if (res.status < 200 || res.status >= 300) {
+    throw new PaymentError(`${provider} request failed: HTTP ${res.status}`, {
+      code: 'HTTP_ERROR',
+      provider,
+      status: res.status,
+      raw: parsed ?? res.body,
+    });
+  }
+  return parsed;
+}
+
+function safeJson(body: string): any {
+  if (!body) return undefined;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Basic-auth header value from `user:pass`. */
+export function basicAuth(user: string, pass: string): string {
+  return 'Basic ' + Buffer.from(`${user}:${pass}`).toString('base64');
+}