OpenSpec Change: enterprise-api-plugin-graphql

Change ID: enterprise-api-plugin-graphql
Package: @suaveplan/api-plugin-graphql
Category: api/data
Target path: api/data/api-plugin-graphql
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-graphql.md

Summary

Deliver @suaveplan/api-plugin-graphql on the genesis branch from scratch at enterprise quality. GraphQL plugin for @suaveplan/api: schema-first with type-safe resolvers, query depth and complexity limiting, persisted queries, DataLoader-based N+1 prevention, subscription support over SSE/WebSocket, query cost analysis, auth integration (@context.user), per-operation rate limiting, and an introspection toggle (disabled in production). Routes: POST /graphql, GET /graphql (GraphiQL in dev). Built on graphql-js with a lightweight schema-builder abstraction. Events: graphql:operation:completed, graphql:error.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/events` (`workspace:^`)	Event bus (subscriptions fan-out)
`@suaveplan/rate-limiter` (`workspace:^`)	Per-operation rate limits
`@suaveplan/error` (`workspace:^`)	`GraphqlPluginError` hierarchy
`graphql` (`catalog:server`)	GraphQL execution engine
`hono` + `zod`	Routes/schemas
`@opentelemetry/api`	OTel

Public API surface

function createGraphqlPlugin(schema: GraphQLSchema, config?: GraphqlPluginConfig): PluginDescriptor

interface GraphqlPluginConfig {
  path?: string           // default: /graphql
  introspection?: boolean // default: false in production
  maxDepth?: number
  maxComplexity?: number
  persistedQueries?: PersistedQueryStore
  playground?: boolean
}

// Helper for building typed resolvers:
function createResolver<TRoot, TArgs, TContext, TResult>(
  fn: (root: TRoot, args: TArgs, ctx: TContext) => Promise<TResult>
): typeof fn

Error codes

type GraphqlPluginErrorCode =
  | "GRAPHQL_QUERY_TOO_DEEP"
  | "GRAPHQL_QUERY_TOO_COMPLEX"
  | "GRAPHQL_PERSISTED_QUERY_NOT_FOUND"
  | "GRAPHQL_EXECUTION_ERROR"
  | "GRAPHQL_PARSE_ERROR"

File layout

api/data/api-plugin-graphql/
  package.json  tsconfig.json  vitest.config.ts
  src/
    index.ts  events.ts  types/  errors/
    core/depth-limiter/  core/complexity/  core/dataloader/  core/persisted-queries/
    middleware/auth-context/
    routes/graphql/
    utils/schema-helpers.ts
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/events, @suaveplan/rate-limiter, graphql.

2.8 KiB Raw Blame History