Skip to content

fix(admin): review follow-up — users.id string, ETL response schemas, retry guards #2410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andrew-bierman merged 1 commit into from
May 12, 2026
Merged

fix(admin): review follow-up — users.id string, ETL response schemas, retry guards #2410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 10 additions & 23 deletions apps/admin/lib/api.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ import type {
BreakdownItemSchema,
CatalogOverviewSchema,
EmbeddingStatsSchema,
EtlFailureSummarySchema,
EtlJobFailuresSchema,
EtlJobSchema,
EtlResponseSchema,
GrowthPointSchema,
Expand Down Expand Up @@ -99,23 +101,23 @@ export async function getUsers({
return unwrap(data, 'users');
}

export async function deleteUser(id: number): Promise<{ success: boolean }> {
const { data, error } = await adminClient.users({ id: String(id) }).delete();
export async function deleteUser(id: string): Promise<{ success: boolean }> {
const { data, error } = await adminClient.users({ id }).delete();
if (error) throwOnError(error);
return unwrap(data, 'deleteUser');
}

export async function hardDeleteUser(
id: number,
id: string,
reason: string,
): Promise<{ success: boolean; purged: boolean }> {
const { data, error } = await adminClient.users({ id: String(id) }).hard.delete({ reason });
const { data, error } = await adminClient.users({ id }).hard.delete({ reason });
if (error) throwOnError(error);
return unwrap(data, 'hardDeleteUser');
}

export async function restoreUser(id: number): Promise<{ success: boolean }> {
const { data, error } = await adminClient.users({ id: String(id) }).restore.post();
export async function restoreUser(id: string): Promise<{ success: boolean }> {
const { data, error } = await adminClient.users({ id }).restore.post();
if (error) throwOnError(error);
return unwrap(data, 'restoreUser');
}
Expand Down Expand Up @@ -343,23 +345,8 @@ export function resetStuckEtlJobs(): Promise<{ reset: number; ids: string[] }> {
return adminFetch('/analytics/catalog/etl/reset-stuck', { method: 'POST' });
}

export type EtlErrorRow = { field: string; reason: string; count: number };

export type EtlFailureSummary = {
topErrors: EtlErrorRow[];
totalInvalidItems: number;
};

export type EtlJobFailures = {
jobId: string;
errorBreakdown: EtlErrorRow[];
samples: Array<{
rowIndex: number;
errors: Array<{ field: string; reason: string; value?: unknown }>;
rawData: unknown;
}>;
totalShown: number;
};
export type EtlFailureSummary = Static<typeof EtlFailureSummarySchema>;
export type EtlJobFailures = Static<typeof EtlJobFailuresSchema>;

export function getEtlFailureSummary(limit = 20): Promise<EtlFailureSummary> {
return adminFetch(`/analytics/catalog/etl/failure-summary?limit=${limit}`);
Expand Down
107 changes: 65 additions & 42 deletions packages/api/src/routes/admin/analytics/catalog.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@ import {
AdminErrorResponses,
BrandRowSchema,
CatalogOverviewSchema,
EtlFailureSummarySchema,
EtlJobFailuresSchema,
EtlResetStuckSchema,
EtlResponseSchema,
EtlRetrySchema,
PriceBucketSchema,
} from '@packrat/api/schemas/admin';
import { queueCatalogETL } from '@packrat/api/services/etl/queue';
Expand Down Expand Up @@ -270,21 +274,22 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
const { limit = 20 } = query;

try {
const rows = await db.execute<{ field: string; reason: string; count: number }>(
sql`
SELECT
err->>'field' AS field,
err->>'reason' AS reason,
COUNT(*)::int AS count
FROM ${invalidItemLogs},
jsonb_array_elements(${invalidItemLogs.errors}) AS err
GROUP BY err->>'field', err->>'reason'
ORDER BY count DESC
LIMIT ${limit}
`,
);

const [total] = await db.select({ n: count() }).from(invalidItemLogs);
const [rows, [total]] = await Promise.all([
db.execute<{ field: string; reason: string; count: number }>(
sql`
SELECT
err->>'field' AS field,
err->>'reason' AS reason,
COUNT(*)::int AS count
FROM ${invalidItemLogs},
jsonb_array_elements(${invalidItemLogs.errors}) AS err
GROUP BY err->>'field', err->>'reason'
ORDER BY count DESC
LIMIT ${limit}
`,
),
db.select({ n: count() }).from(invalidItemLogs),
]);

return {
topErrors: rows.rows.map((r) => ({
Expand All @@ -306,6 +311,7 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
query: z.object({
limit: z.coerce.number().int().min(1).max(100).optional().default(20),
}),
response: { 200: EtlFailureSummarySchema, ...AdminErrorResponses },
detail: { tags: ['Admin'], summary: 'Top ETL validation failure patterns' },
},
)
Expand All @@ -319,26 +325,27 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
const { limit = 50 } = query;

try {
const samples = await db
.select()
.from(invalidItemLogs)
.where(eq(invalidItemLogs.jobId, params.jobId))
.orderBy(invalidItemLogs.rowIndex)
.limit(limit);

const breakdown = await db.execute<{ field: string; reason: string; count: number }>(
sql`
SELECT
err->>'field' AS field,
err->>'reason' AS reason,
COUNT(*)::int AS count
FROM ${invalidItemLogs},
jsonb_array_elements(${invalidItemLogs.errors}) AS err
WHERE ${invalidItemLogs.jobId} = ${params.jobId}
GROUP BY err->>'field', err->>'reason'
ORDER BY count DESC
`,
);
const [samples, breakdown] = await Promise.all([
db
.select()
.from(invalidItemLogs)
.where(eq(invalidItemLogs.jobId, params.jobId))
.orderBy(invalidItemLogs.rowIndex)
.limit(limit),
db.execute<{ field: string; reason: string; count: number }>(
sql`
SELECT
err->>'field' AS field,
err->>'reason' AS reason,
COUNT(*)::int AS count
FROM ${invalidItemLogs},
jsonb_array_elements(${invalidItemLogs.errors}) AS err
WHERE ${invalidItemLogs.jobId} = ${params.jobId}
GROUP BY err->>'field', err->>'reason'
ORDER BY count DESC
`,
),
]);

return {
jobId: params.jobId,
Expand All @@ -363,10 +370,11 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
}
},
{
params: z.object({ jobId: z.string() }),
params: z.object({ jobId: z.string().uuid() }),
query: z.object({
limit: z.coerce.number().int().min(1).max(200).optional().default(50),
}),
response: { 200: EtlJobFailuresSchema, ...AdminErrorResponses },
detail: { tags: ['Admin'], summary: 'Validation failures for a specific ETL job' },
},
)
Expand Down Expand Up @@ -394,7 +402,10 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
return status(500, { error: 'Failed to reset stuck jobs', code: 'ETL_RESET_STUCK_ERROR' });
}
},
{ detail: { tags: ['Admin'], summary: 'Mark stuck running ETL jobs as failed' } },
{
response: { 200: EtlResetStuckSchema, ...AdminErrorResponses },
detail: { tags: ['Admin'], summary: 'Mark stuck running ETL jobs as failed' },
},
)

// ─── Retry a failed job ───────────────────────────────────────────────────────
Expand All @@ -412,9 +423,12 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
.limit(1);

if (!original) return status(404, { error: 'ETL job not found' });
if (original.status === 'running')
if (original.status !== 'failed')
return status(409, {
error: 'Job is still running — wait for it to complete or reset stuck jobs first',
error:
original.status === 'running'
? 'Job is still running — wait for it to complete or reset stuck jobs first'
: 'Only failed jobs can be retried',
});

const newJobId = crypto.randomUUID();
Expand All @@ -432,16 +446,25 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
startedAt: new Date(),
});

await queueCatalogETL({ queue: env.ETL_QUEUE, objectKeys: [objectKey], jobId: newJobId });
try {
await queueCatalogETL({ queue: env.ETL_QUEUE, objectKeys: [objectKey], jobId: newJobId });
} catch (enqueueErr) {
await db
.update(etlJobs)
.set({ status: 'failed', completedAt: new Date() })
.where(eq(etlJobs.id, newJobId));
throw enqueueErr;
}

return { success: true, newJobId, objectKey };
return { success: true as const, newJobId, objectKey };
} catch (error) {
console.error('ETL retry error:', error);
return status(500, { error: 'Failed to retry ETL job', code: 'ETL_RETRY_ERROR' });
}
},
{
params: z.object({ jobId: z.string() }),
params: z.object({ jobId: z.string().uuid() }),
response: { 200: EtlRetrySchema, ...AdminErrorResponses },
detail: { tags: ['Admin'], summary: 'Retry a failed ETL job' },
},
);
36 changes: 35 additions & 1 deletion packages/api/src/schemas/admin.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ export const AdminStatsSchema = t.Object({
// ─── Users ────────────────────────────────────────────────────────────────────

export const AdminUserItemSchema = t.Object({
id: t.Number(),
id: t.String(),
email: t.String(),
firstName: t.Nullable(t.String()),
lastName: t.Nullable(t.String()),
Expand Down Expand Up @@ -176,6 +176,40 @@ export const EmbeddingStatsSchema = t.Object({
coveragePct: t.Number(),
});

const EtlErrorRowSchema = t.Object({ field: t.String(), reason: t.String(), count: t.Number() });

export const EtlFailureSummarySchema = t.Object({
topErrors: t.Array(EtlErrorRowSchema),
totalInvalidItems: t.Number(),
});

export const EtlJobFailuresSchema = t.Object({
jobId: t.String(),
errorBreakdown: t.Array(EtlErrorRowSchema),
samples: t.Array(
t.Object({
rowIndex: t.Number(),
errors: t.Array(
t.Object({
field: t.String(),
reason: t.String(),
value: t.Optional(t.Unknown()),
}),
),
rawData: t.Unknown(),
}),
),
totalShown: t.Number(),
});

export const EtlResetStuckSchema = t.Object({ reset: t.Number(), ids: t.Array(t.String()) });

export const EtlRetrySchema = t.Object({
success: t.Literal(true),
newJobId: t.String(),
objectKey: t.String(),
});

// ─── Trails ───────────────────────────────────────────────────────────────────

export const TrailSearchItemSchema = t.Object({
Expand Down
Loading