@perform/errors and @perform/types

These two packages define the vocabulary every module uses. @perform/types has no dependencies. @perform/errors depends on it and on Express and Zod types.

`@perform/types`

packages/types/src/index.ts. Constants are as const objects with a union type of the same name, not TypeScript enums.

`ErrorCode`

export const ErrorCode = {
  INTERNAL: 'INTERNAL',
  BAD_REQUEST: 'BAD_REQUEST',
  UNAUTHORIZED: 'UNAUTHORIZED',
  FORBIDDEN: 'FORBIDDEN',
  NOT_FOUND: 'NOT_FOUND',
  CONFLICT: 'CONFLICT',
  RATE_LIMITED: 'RATE_LIMITED',
  VALIDATION: 'VALIDATION',
  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
} as const;
export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];

Response types

export type ApiError = {
  ok: false;
  code: ErrorCode;
  message: string;
  requestId?: string;
  details?: unknown;
};

export type ApiSuccess<T> = { ok: true; data: T; requestId?: string };
export type ApiResponse<T> = ApiSuccess<T> | ApiError;

export type Paginated<T> = { items: T[]; total: number; page: number; pageSize: number };

These describe the /v1 envelope. Client code can import them to type responses.

`StudioRole`

export const StudioRole = {
  OWNER: 'OWNER',
  HEAD_COACH: 'HEAD_COACH',
  SUB_COACH: 'SUB_COACH',
  TRAINEE: 'TRAINEE',
} as const;

The role on req.auth. See Roles and permissions.

Staff permission groups

export const StaffPermissionGroup = {
  SUPER_ADMIN: 'super_admin',
  FULL_ACCESS: 'full_access',
  STANDARD: 'standard',
  READ_ONLY: 'read_only',
} as const;

export type OrganizationMemberRole = 'admin' | 'member';

export function organizationRoleForStaff(
  permissionGroup: string | null | undefined,
  coachRole: string,
): OrganizationMemberRole;

organizationRoleForStaff returns admin when the permission group is super_admin or the coach role is HEAD_COACH, otherwise member. @repo/auth uses it when it creates the better-auth membership for a staff member. It lives here because both the auth package and core-api need the same answer.

`STUDIO_ONBOARDING_WINDOW_MS`

72 hours in milliseconds. How long after its creation a studio that the /start wizard bootstrapped still counts as in the wizard when its owner never finished it. Plan limits exempt the wizard’s own invites and import during that window. Read by billing.limits.ts in core-api and by studio-lifecycle.ts in @repo/auth.

`@perform/errors`

packages/errors/src/index.ts.

Export	Kind
`ErrorCode`	Re-export from `@perform/types`
`AppError`	Class
`toApiError(err, requestId?)`	Function
`errorMiddleware`	Express error handler
`notFoundMiddleware`	Express handler

`AppError`

new AppError(code: ErrorCode, message: string, options?: { status?: number; details?: unknown })

Property	Value
`name`	`'AppError'`
`code`	The `ErrorCode`
`status`	`options.status`, else the default for the code, else 500
`details`	Set only when `options.details` is not `undefined`

Default status per code:

Code	Status
`INTERNAL`	500
`BAD_REQUEST`	400
`UNAUTHORIZED`	401
`FORBIDDEN`	403
`NOT_FOUND`	404
`CONFLICT`	409
`RATE_LIMITED`	429
`VALIDATION`	422
`SERVICE_UNAVAILABLE`	503

Examples from the codebase:

throw new AppError(ErrorCode.NOT_FOUND, 'product not found');

throw new AppError(ErrorCode.FORBIDDEN, 'app access is paused', {
  details: { reason: 'APP_LOCKED' },
});

// a body parser error keeps its own 4xx status under BAD_REQUEST
new AppError(ErrorCode.BAD_REQUEST, 'payload too large', { status: 413 });

AppError extends Error, so instanceof AppError works across the workspace as long as there is one copy of the package, which the workspace guarantees.

`toApiError(err, requestId?)`

Turns anything thrown into an ApiError body. It is what the middleware sends, and it is exported so other code can build the same body. The order of checks:

An AppError, or an error that mapPrismaError or mapBodyParserError can turn into one. details is copied when present.
A ZodError: code VALIDATION, message validation failed, details as { path, message } per issue.
Anything else: code INTERNAL, message internal server error.

The internal mappers are not exported:

mapPrismaError matches on err.name and err.code, so it does not need to import Prisma.
mapBodyParserError matches errors that have a string type, expose === true and a numeric 4xx status.
isConnectionError treats messages containing connection terminated, connection closed, econnrefused, connection refused or connection reset as a database outage.

The full mapping table is on Responses and errors.

`errorMiddleware`

export const errorMiddleware: ErrorRequestHandler;

Computes the status (AppError.status, 422 for a ZodError, else 500), logs one line with console.error for 5xx or console.warn for 4xx, and sends toApiError(err, requestId). Register it last. It must have the four argument signature Express uses to recognize an error handler, which the exported constant already has.

`notFoundMiddleware`

Answers 404 with route not found: METHOD /original/url. Register it after every router and before errorMiddleware.

Using them outside core-api

A new Express service in the workspace gets the same envelope by registering the two middlewares and throwing AppError:

import { AppError, ErrorCode, errorMiddleware, notFoundMiddleware } from '@perform/errors';

app.use('/things', thingsRouter);
app.use(notFoundMiddleware);
app.use(errorMiddleware);

Lanes that need a different wire format register their own error handler on the router, as the automation API and the signing lane do. Their handlers still receive AppError and read code, status and details from it.

Adding an error code

Add the key to ErrorCode in @perform/types.
Add its status to STATUS_BY_CODE in @perform/errors. The record type is keyed by ErrorCode, so the compiler reports a missing entry.
Check the automation lane’s STATUS_BY_ERROR_CODE map and add the code there if it should not fall through to 400.
Rebuild both packages.
Tell the web and mobile teams. Clients switch on code, and an unknown code usually falls into a generic error path.

Prefer a details.reason on an existing code over a new code. A new sub reason is backward compatible for clients. A new top level code is not.

​@perform/types

​ErrorCode

​Response types

​StudioRole

​Staff permission groups

​STUDIO_ONBOARDING_WINDOW_MS

​@perform/errors

​AppError

​toApiError(err, requestId?)

​errorMiddleware

​notFoundMiddleware

​Using them outside core-api

​Adding an error code