---
name: api-create-gql-query
description: Add a new GraphQL query endpoint with type safety, GraphORM integration, and tests
argument-hint: "[query name and purpose]"
---

# Add a New GraphQL Query to daily-api

You are adding a new GraphQL query endpoint for daily-api. Follow this skill step by step.

## Context Loading

Before writing any code, read these files for code style rules and GraphQL conventions:

1. `AGENTS.md` (project root) — code style, architecture, best practices
2. `src/graphorm/AGENTS.md` — GraphORM patterns for N+1 prevention

These are the source of truth for all code style decisions. Do not deviate from them.

## Step 0 — Gather Requirements

Before writing any code, ask the user the following questions **in this order**:

### 1. Which schema domain?

> **Which schema file does this query belong in?**

Check existing files in `src/schema/` (e.g., `posts.ts`, `users.ts`, `keywords.ts`, `campaigns.ts`, `sources.ts`, `organizations.ts`, etc.) and `src/graphql.ts` imports. Use an existing domain file if the query fits, or create a new one if it represents a new domain.

### 2. Return type

> **What does the query return?** One of:
>
> - **(a)** Single entity — `graphorm.queryOne<T>()` / `graphorm.queryOneOrFail<T>()`
> - **(b)** List of entities — `graphorm.query<T>()`
> - **(c)** Paginated list (Relay-style) — `graphorm.queryPaginated<T>()`

Check existing GQL types in the target schema file and `src/schema/common.ts` for reusable types (`PageInfo`, `ConnectionArgs`, scalars like `DateTime`, `JSONObject`).

### 3. Input arguments and validation

> **What parameters does the query accept?**

For every `String` argument, ask what it represents so the correct Zod validator is chosen (e.g., `z.uuid()` for IDs, `z.email()` for emails, `z.url()` for URLs, `z.string().min(1)` for free text). All query input parameters must be validated with a Zod schema — this is not optional.

### 4. Authentication requirements

> **What auth level is needed?** One of:
>
> - **(a)** Public (no auth) — resolver uses `Context`
> - **(b)** Authenticated — resolver uses `AuthContext`, add `@auth` directive
> - **(c)** Moderator-only — add `@auth(requires: [MODERATOR])` directive
> - **(d)** Plus subscriber — add `@feedPlus` directive

### 5. Business logic

> **What data should the query return and what filtering/sorting is needed?**

---

## Step 1 — Check for Reusable Types

Before creating new types, check:

- **Target schema file** — existing GQL types and TypeScript types
- **`src/schema/common.ts`** — shared types (`PageInfo`, connection patterns, scalars)
- **`src/entity/`** — existing TypeORM entities that map to the desired return type
- **`src/graphorm/index.ts`** — existing GraphORM type configurations
- **`src/common/schema/`** — existing Zod schemas that already validate similar input

Only create new types if nothing reusable exists.

---

## Step 2 — Define Zod Validation Schema

**Mandatory for all queries that accept input arguments.**

Create or update a Zod schema in `src/common/schema/` with `Schema` suffix. This project uses **Zod 4.x** — primitive validators are top-level: `z.email()`, `z.uuid()`, `z.url()` (not `z.string().email()`).

| GQL Type | Use Case | Zod Validator |
|---|---|---|
| `String!` | ID (UUID) | `z.uuid()` |
| `String!` | ID (non-UUID) | `z.string().min(1)` |
| `String!` | Email | `z.email()` |
| `String!` | URL | `z.url()` |
| `String!` | Free text | `z.string().min(1)` |
| `String` (nullable) | Any | appropriate validator with `.nullish()` |
| `Int` / `Int!` | Number | `z.number().int()` with `.min()`/`.max()` |
| `Boolean` | Flag | `z.boolean()` |

Rules:
- Never re-export inferred types — use `z.infer<typeof schema>` at point of use
- Export only the schema, not the inferred type
- For ambiguous `String` args, ask the user what the value represents before choosing a validator

---

## Step 3 — Define TypeScript Types

If new types are needed, add a TypeScript `type` (not `interface` — per AGENTS.md) for the GQL return type in the schema file.

Exception: some existing schema files already use `interface` — follow the pattern in the specific file being modified.

---

## Step 4 — Define GraphQL Schema (typeDefs)

Add to the `typeDefs` template literal (using `/* GraphQL */` tag) in the schema file:

- New types if needed
- `extend type Query { ... }` with the new query field and auth directives

For paginated queries, define `Edge` and `Connection` types following the pattern in `src/schema/campaigns.ts`.

---

## Step 5 — Write the Resolver

All queries must use **GraphORM** (not TypeORM repositories). Wrap resolvers in `traceResolvers()`. Validate input with the Zod schema from Step 2 using `schema.parse(args)`. Pass `true` as the 4th argument for read replica when eventual consistency is acceptable. Filter at the database level via the builder callback, not in JavaScript.

Reference examples:
- **Single entity**: `src/schema/keywords.ts` → `keyword`, `src/schema/campaigns.ts` → `campaignById`
- **List**: `src/schema/keywords.ts` → `randomPendingKeyword`
- **Paginated**: `src/schema/campaigns.ts` → `campaignsList`

---

## Step 6 — Add GraphORM Configuration (if needed)

If the query returns a new entity type or needs custom field mappings, add configuration to `src/graphorm/index.ts`. Define `requiredColumns`, field transforms, custom relations as needed. Reference `src/graphorm/AGENTS.md` for patterns.

Skip if using an already-configured entity type.

---

## Step 7 — Register in GraphQL Schema (if new domain file)

**Only needed when creating a new schema file.**

In `src/graphql.ts`:
1. Add `import * as newDomain from './schema/newDomain'`
2. Add `newDomain.typeDefs` to the `typeDefs` array
3. Add `newDomain.resolvers` to the `merge()` call

---

## Step 8 — Write Integration Tests

Create or update test file in `__tests__/`. Reference: `__tests__/keywords.ts` for the full test structure.

Use the `initializeGraphQLTesting` + `MockContext` + `GraphQLTestClient` pattern from `__tests__/helpers`.

Test cases to include:
1. **Auth/authorization checks** (if applicable)
2. **Success path** with expected response shape (use `toMatchObject`/`toEqual`)
3. **Validation failure** (invalid input rejected by Zod schema)
4. **Edge cases** (not found, empty results)

Run with: `NODE_ENV=test npx jest __tests__/<test-file>.ts --testEnvironment=node --runInBand`

---

## File Locations Quick Reference

| Purpose | Path |
|---|---|
| GraphQL schema & resolvers | `src/schema/<domain>.ts` |
| Schema registration | `src/graphql.ts` |
| GraphORM configuration | `src/graphorm/index.ts` |
| Shared GQL types | `src/schema/common.ts` |
| Entity definitions | `src/entity/` |
| Zod validation schemas | `src/common/schema/` |
| Test file | `__tests__/<domain>.ts` |
| GraphORM docs | `src/graphorm/AGENTS.md` |
| Code style reference | `AGENTS.md` |

## Instructions

When the user invokes this skill:

1. Read `AGENTS.md` and `src/graphorm/AGENTS.md` for context
2. Complete Step 0 — ask all requirement questions before writing any code. For every `String` argument, ask what it represents so the right Zod validator is chosen.
3. Work through Steps 1–8 in order
4. Reference actual codebase examples (`src/schema/keywords.ts` for simple queries, `src/schema/campaigns.ts` for paginated) rather than relying solely on templates
5. Follow all code style rules from AGENTS.md (arrow functions, no unnecessary comments, type over interface, no barrel imports, etc.)
6. Verify build and lint pass: `pnpm run build && pnpm run lint`