# 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

```ts
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

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

---

## File layout

```text
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`.