feat: add GET /api/creators/:address/campaigns endpoint

Adds a creator-scoped campaign listing endpoint that reuses the same
filtering, sorting, and pagination logic as GET /api/campaigns.

- Add `creator` filter to ListCampaignsOptions in campaignStore.listCampaigns
- Extract buildCampaignListOptions/buildCampaignListResponseBody helpers
  so /api/campaigns and /api/creators/:address/campaigns share identical
  query parsing and response shaping
- Validate the :address path param against the Stellar account ID format
  (consistent with how creator/contributor addresses are validated
  elsewhere in the API), returning 400 VALIDATION_ERROR on malformed input
- Unknown but well-formed addresses return an empty data array with 200
- Register the new path in the OpenAPI spec
- Add endpoint test coverage: invalid address, unknown address, creator
  filtering, shared filters/pagination behavior

Closes #557

Author: MorsH14

backend/src/api.test.ts

@@ -430,6 +430,99 @@ describe('Campaign maxPerContributor Field', () => {
   });
 });
 
+describe('GET /api/creators/:address/campaigns', () => {
+  async function get(apiPath: string) {
+    const response = await fetch(`${baseUrl}${apiPath}`);
+    const data = await response.json().catch(() => null);
+    return { status: response.status, data };
+  }
+
+  const OTHER_CREATOR = `G${'D'.repeat(55)}`;
+
+  it('returns 400 for a malformed address', async () => {
+    const res = await get('/api/creators/not-a-valid-address/campaigns');
+    expect(res.status).toBe(400);
+    expect(res.data.error.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('returns 400 for an address of the wrong length', async () => {
+    const res = await get(`/api/creators/${'G' + 'A'.repeat(10)}/campaigns`);
+    expect(res.status).toBe(400);
+    expect(res.data.error.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('returns an empty array for a well-formed address with no campaigns', async () => {
+    const res = await get(`/api/creators/${CREATOR}/campaigns`);
+    expect(res.status).toBe(200);
+    expect(res.data.data).toEqual([]);
+    expect(res.data.pagination.total).toBe(0);
+  });
+
+  it('returns only campaigns created by the given address', async () => {
+    const now = Math.floor(Date.now() / 1000);
+
+    const mine = await post('/api/campaigns', {
+      creator: CREATOR,
+      title: 'My campaign',
+      description: 'Campaign owned by the queried creator address',
+      acceptedTokens: ['USDC'],
+      targetAmount: 100,
+      deadline: now + 3600,
+    });
+    expect(mine.status).toBe(201);
+
+    const other = await post('/api/campaigns', {
+      creator: OTHER_CREATOR,
+      title: 'Someone else campaign',
+      description: 'Campaign owned by a different creator address',
+      acceptedTokens: ['USDC'],
+      targetAmount: 100,
+      deadline: now + 3600,
+    });
+    expect(other.status).toBe(201);
+
+    const res = await get(`/api/creators/${CREATOR}/campaigns`);
+    expect(res.status).toBe(200);
+    expect(res.data.data).toHaveLength(1);
+    expect(res.data.data[0].creator).toBe(CREATOR);
+    expect(res.data.data[0].id).toBe(mine.data.data.id);
+    // Response schema matches GET /api/campaigns (data + pagination + progress per item)
+    expect(res.data.data[0].progress).toBeDefined();
+    expect(res.data.pagination).toMatchObject({ total: 1, page: 1 });
+  });
+
+  it('supports the same filters and pagination as GET /api/campaigns', async () => {
+    const now = Math.floor(Date.now() / 1000);
+
+    for (const asset of ['USDC', 'XLM']) {
+      const res = await post('/api/campaigns', {
+        creator: CREATOR,
+        title: `${asset} campaign`,
+        description: `Campaign accepting ${asset} for pagination test`,
+        acceptedTokens: [asset],
+        targetAmount: 100,
+        deadline: now + 3600,
+      });
+      expect(res.status).toBe(201);
+    }
+
+    const filtered = await get(`/api/creators/${CREATOR}/campaigns?asset=XLM`);
+    expect(filtered.status).toBe(200);
+    expect(filtered.data.data.every((c: { assetCode: string }) => c.assetCode === 'XLM')).toBe(true);
+
+    const paginated = await get(`/api/creators/${CREATOR}/campaigns?page=1&limit=1`);
+    expect(paginated.status).toBe(200);
+    expect(paginated.data.data).toHaveLength(1);
+    expect(paginated.data.pagination).toMatchObject({ page: 1, limit: 1, total: 2 });
+  });
+
+  it('returns 400 for invalid pagination parameters, matching GET /api/campaigns', async () => {
+    const res = await get(`/api/creators/${CREATOR}/campaigns?page=1`);
+    expect(res.status).toBe(400);
+    expect(res.data.error.code).toBe('VALIDATION_ERROR');
+  });
+});
+
 describe('GET /api/stats', () => {
   it('returns aggregate metrics in the correct format', async () => {
     const res = await get('/api/stats');

backend/src/index.ts

@@ -55,10 +55,12 @@ import {
   parsePledgeListPaginationQuery,
   reconcilePledgePayloadSchema,
   refundPayloadSchema,
+  stellarAccountIdSchema,
   zodIssuesToErrorMessage,
   zodIssuesToValidationIssues,
   parseCampaignListQuery,
   normalizeQueryValue,
+  type CampaignListQueryParams,
 } from './validation/schemas';
 import { generateOpenApiDocument } from './openapi';
 import { logError, logInfo } from './logger';
@@ -232,6 +234,30 @@ function parseCampaignId(
   return { ok: true, value: parsed.data };
 }
 
+function parseCreatorAddress(
+  addressRaw: unknown,
+): { ok: true; value: string } | { ok: false; issues: z.ZodIssue[] } {
+  if (typeof addressRaw !== 'string') {
+    return {
+      ok: false,
+      issues: [
+        {
+          code: 'custom',
+          message: 'address must be a string.',
+          path: ['address'],
+        },
+      ],
+    };
+  }
+
+  const parsed = stellarAccountIdSchema.safeParse(addressRaw);
+  if (!parsed.success) {
+    return { ok: false, issues: parsed.error.issues };
+  }
+
+  return { ok: true, value: parsed.data };
+}
+
 export function normalizeAssetFilter(assetRaw: unknown): string | undefined {
   const asset = normalizeQueryValue(assetRaw)?.toUpperCase();
   if (!asset) {
@@ -388,32 +414,10 @@ app.get('/api/health/deep', applyRateLimit(1000), async (_req: Request, res: Res
   }
 });
 
-app.get('/api/campaigns', (req: Request, res: Response) => {
-  const queryResult = parseCampaignListQuery(req.query as Record<string, unknown>);
-  if (!queryResult.ok) {
-    sendValidationError(queryResult.issues);
-  }
-
-  const params = queryResult.data;
-
-  // Build a stable cache key from the sorted query string
-  const qs = Object.keys(req.query as Record<string, unknown>)
-    .sort()
-    .map((k) => `${k}=${(req.query as Record<string, unknown>)[k]}`)
-    .join('&');
-  const cacheKey = buildCampaignCacheKey(qs);
-
-  const cached = getCampaignCacheEntry(cacheKey);
-  if (cached) {
-    const cachedData = JSON.parse(cached);
-    res.setHeader('Cache-Control', 'max-age=5');
-    res.setHeader('X-Cache', 'HIT');
-    res.setHeader('X-Total-Count', String(cachedData.pagination.total));
-    res.setHeader('Content-Type', 'application/json');
-    res.send(cached);
-    return;
-  }
-
+function buildCampaignListOptions(
+  params: CampaignListQueryParams,
+  extra?: Partial<ListCampaignsOptions>,
+): ListCampaignsOptions {
   const listOptions: ListCampaignsOptions = {
     searchQuery: params.search || params.q,
     assetCodes: params.asset,
@@ -423,12 +427,19 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
     order: params.order,
     createdAfter: params.createdAfter,
     createdBefore: params.createdBefore,
+    ...extra,
   };
   if (params.page !== undefined) {
     listOptions.page = params.page;
     listOptions.limit = params.limit;
   }
+  return listOptions;
+}
 
+function buildCampaignListResponseBody(
+  params: CampaignListQueryParams,
+  listOptions: ListCampaignsOptions,
+): { totalCount: number; body: string } {
   const { campaigns, totalCount } = listCampaigns(listOptions);
 
   const data = campaigns.map((campaign) => ({
@@ -441,7 +452,7 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
   const totalPages =
     params.limit === undefined || limit <= 0 ? 1 : Math.max(1, Math.ceil(totalCount / limit));
 
-  const responseBody = JSON.stringify({
+  const body = JSON.stringify({
     data,
     pagination: {
       total: totalCount,
@@ -451,13 +462,65 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
     },
   });
 
-  setCampaignCacheEntry(cacheKey, responseBody);
+  return { totalCount, body };
+}
+
+app.get('/api/campaigns', (req: Request, res: Response) => {
+  const queryResult = parseCampaignListQuery(req.query as Record<string, unknown>);
+  if (!queryResult.ok) {
+    sendValidationError(queryResult.issues);
+  }
+
+  const params = queryResult.data;
+
+  // Build a stable cache key from the sorted query string
+  const qs = Object.keys(req.query as Record<string, unknown>)
+    .sort()
+    .map((k) => `${k}=${(req.query as Record<string, unknown>)[k]}`)
+    .join('&');
+  const cacheKey = buildCampaignCacheKey(qs);
+
+  const cached = getCampaignCacheEntry(cacheKey);
+  if (cached) {
+    const cachedData = JSON.parse(cached);
+    res.setHeader('Cache-Control', 'max-age=5');
+    res.setHeader('X-Cache', 'HIT');
+    res.setHeader('X-Total-Count', String(cachedData.pagination.total));
+    res.setHeader('Content-Type', 'application/json');
+    res.send(cached);
+    return;
+  }
+
+  const listOptions = buildCampaignListOptions(params);
+  const { totalCount, body } = buildCampaignListResponseBody(params, listOptions);
+
+  setCampaignCacheEntry(cacheKey, body);
 
   res.setHeader('Cache-Control', 'max-age=5');
   res.setHeader('X-Cache', 'MISS');
   res.setHeader('X-Total-Count', String(totalCount));
   res.setHeader('Content-Type', 'application/json');
-  res.send(responseBody);
+  res.send(body);
+});
+
+app.get('/api/creators/:address/campaigns', (req: Request, res: Response) => {
+  const parsedAddress = parseCreatorAddress(req.params.address);
+  if (!parsedAddress.ok) {
+    sendValidationError(parsedAddress.issues);
+  }
+
+  const queryResult = parseCampaignListQuery(req.query as Record<string, unknown>);
+  if (!queryResult.ok) {
+    sendValidationError(queryResult.issues);
+  }
+
+  const params = queryResult.data;
+  const listOptions = buildCampaignListOptions(params, { creator: parsedAddress.value });
+  const { totalCount, body } = buildCampaignListResponseBody(params, listOptions);
+
+  res.setHeader('X-Total-Count', String(totalCount));
+  res.setHeader('Content-Type', 'application/json');
+  res.send(body);
 });
 
 app.get('/api/campaigns/:id', (req: Request, res: Response) => {

backend/src/openapi.ts

@@ -463,45 +463,39 @@ registry.registerPath({
   },
 });
 
+const campaignListQuerySchema = z.object({
+  page: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .openapi({ description: 'Page number (requires limit).' }),
+  limit: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .openapi({ description: 'Items per page (requires page).' }),
+  q: z.string().optional().openapi({ description: 'Search query (title, creator, or id).' }),
+  search: z.string().optional().openapi({ description: 'Alias for q.' }),
+  asset: z.string().optional().openapi({ description: 'Comma-separated list of asset codes.' }),
+  status: z.enum(['open', 'funded', 'claimed', 'failed']).optional(),
+  sort: z.enum(['createdAt', 'deadline', 'pledgedAmount', 'targetAmount']).optional(),
+  order: z.enum(['asc', 'desc']).optional(),
+  includeDeleted: z.enum(['true', 'false']).optional(),
+  createdAfter: z.string().datetime().optional().openapi({ description: 'ISO 8601 timestamp.' }),
+  createdBefore: z.string().datetime().optional().openapi({ description: 'ISO 8601 timestamp.' }),
+});
+
 registry.registerPath({
   method: 'get',
   path: '/api/campaigns',
   tags: ['Campaigns'],
   summary: 'List campaigns',
   description: 'List campaigns with optional filtering, sorting, and pagination.',
   request: {
-    query: z.object({
-      page: z.coerce
-        .number()
-        .int()
-        .min(1)
-        .optional()
-        .openapi({ description: 'Page number (requires limit).' }),
-      limit: z.coerce
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .optional()
-        .openapi({ description: 'Items per page (requires page).' }),
-      q: z.string().optional().openapi({ description: 'Search query (title, creator, or id).' }),
-      search: z.string().optional().openapi({ description: 'Alias for q.' }),
-      asset: z.string().optional().openapi({ description: 'Comma-separated list of asset codes.' }),
-      status: z.enum(['open', 'funded', 'claimed', 'failed']).optional(),
-      sort: z.enum(['createdAt', 'deadline', 'pledgedAmount', 'targetAmount']).optional(),
-      order: z.enum(['asc', 'desc']).optional(),
-      includeDeleted: z.enum(['true', 'false']).optional(),
-      createdAfter: z
-        .string()
-        .datetime()
-        .optional()
-        .openapi({ description: 'ISO 8601 timestamp.' }),
-      createdBefore: z
-        .string()
-        .datetime()
-        .optional()
-        .openapi({ description: 'ISO 8601 timestamp.' }),
-    }),
+    query: campaignListQuerySchema,
   },
   responses: {
     200: {
@@ -512,6 +506,26 @@ registry.registerPath({
   },
 });
 
+registry.registerPath({
+  method: 'get',
+  path: '/api/creators/{address}/campaigns',
+  tags: ['Campaigns'],
+  summary: "List a creator's campaigns",
+  description:
+    'List all campaigns created by the given Stellar address, with the same filtering, sorting, and pagination as GET /api/campaigns. Returns an empty list for addresses with no campaigns.',
+  request: {
+    params: z.object({ address: stellarAddressSchema }),
+    query: campaignListQuerySchema,
+  },
+  responses: {
+    200: {
+      description: "Paginated list of the creator's campaigns",
+      content: { 'application/json': { schema: registeredSchemas.CampaignListResponse } },
+    },
+    400: validationErrorResponse,
+  },
+});
+
 registry.registerPath({
   method: 'post',
   path: '/api/campaigns',

backend/src/services/campaignStore.ts

@@ -282,6 +282,7 @@ export type SortOrder = 'asc' | 'desc';
 
 export interface ListCampaignsOptions {
   searchQuery?: string;
+  creator?: string;
   assetCode?: string;
   assetCodes?: string[];
   status?: CampaignStatus;
@@ -375,6 +376,10 @@ if (options?.searchQuery && options.searchQuery.trim()) {
     params.push(creatorExactTerm, exactTerm);
   }
 }
+  if (options?.creator) {
+    whereClauses.push(`LOWER(campaigns.creator) = LOWER(?)`);
+    params.push(options.creator);
+  }
   if (options?.assetCode) {
     whereClauses.push(`campaigns.accepted_tokens_json LIKE ?`);
     params.push(`%${options.assetCode.toUpperCase()}%`);