SoException

abstract class SoException extends Error {
  constructor(
    public readonly statusCode: number,
    public message: LocalizedString,
    public payload?: unknown,
  );
}

readonly statusCode: number

message: LocalizedString;

payload?: unknown

throw new BadRequestException("Invalid email format", {
  field: "email",
  providedValue: "invalid-email",
  expectedFormat: "user@example.com",
});

function isSoException(err: unknown): err is SoException;

try {
  // Some operation
} catch (err) {
  if (isSoException(err)) {
    console.log(`Status: ${err.statusCode}`);
    console.log(`Message: ${err.message}`);
    console.log(`Payload:`, err.payload);
  } else {
    // Handle other error types
  }
}

class BadRequestException extends SoException

@api()
async createUser(email: string, password: string) {
  if (!email.includes("@")) {
    throw new BadRequestException("Invalid email format");
  }

  if (password.length < 8) {
    throw new BadRequestException("Password must be at least 8 characters", {
      minLength: 8,
      providedLength: password.length
    });
  }

  // User creation logic
}

class UnauthorizedException extends SoException

@api()
async getMyProfile(ctx: Context) {
  if (!ctx.user) {
    throw new UnauthorizedException("Login required");
  }

  return this.findById(ctx.user.id);
}

class NotFoundException extends SoException

@api()
async getUserById(id: number) {
  const user = await this.findById(id);

  if (!user) {
    throw new NotFoundException(`User not found (ID: ${id})`);
  }

  return user;
}

class InternalServerErrorException extends SoException

@api()
async processPayment(orderId: number) {
  try {
    const result = await externalPaymentAPI.charge(orderId);
    return result;
  } catch (err) {
    throw new InternalServerErrorException(
      "Error occurred during payment processing",
      { orderId, originalError: err }
    );
  }
}

class ServiceUnavailableException extends SoException

@api()
async getRecommendations() {
  if (!this.mlServiceAvailable) {
    throw new ServiceUnavailableException(
      "Recommendation service is temporarily unavailable"
    );
  }

  return this.fetchRecommendations();
}

class TargetNotFoundException extends SoException

@api()
async deleteUserPosts(userId: number) {
  const posts = await this.findByUserId(userId);

  if (posts.length === 0) {
    throw new TargetNotFoundException(
      `No posts to delete (User ID: ${userId})`
    );
  }

  await this.deleteMany(posts.map(p => p.id));
}

class AlreadyProcessedException extends SoException

@api()
async processOrder(orderId: number) {
  const order = await this.findById(orderId);

  if (order.status === "processed") {
    throw new AlreadyProcessedException(
      `Order has already been processed (ID: ${orderId})`,
      { processedAt: order.processedAt }
    );
  }

  // Order processing logic
}

class DuplicateRowException extends SoException

@api()
async createUser(email: string, username: string) {
  const existingUser = await this.findByEmail(email);

  if (existingUser) {
    throw new DuplicateRowException(
      "Email already registered",
      { field: "email", value: email }
    );
  }

  // User creation logic
}

// Exception thrown in API method
@api()
async createPost(title: string) {
  if (!title) {
    throw new BadRequestException("Title is required");
  }
  // ...
}

// Client receives:
// HTTP 400 Bad Request
// {
//   "statusCode": 400,
//   "message": "Title is required"
// }

throw new BadRequestException("Invalid data", {
  errors: [
    { field: "email", message: "Email format is invalid" },
    { field: "age", message: "Age must be greater than 0" },
  ],
});

// Client response:
// HTTP 400 Bad Request
// {
//   "statusCode": 400,
//   "message": "Invalid data",
//   "payload": {
//     "errors": [
//       { "field": "email", "message": "Email format is invalid" },
//       { "field": "age", "message": "Age must be greater than 0" }
//     ]
//   }
// }

// Using Guards (recommended)
@api({ guards: ["user"] })
async getMyData(ctx: Context) {
  // ctx.user is guaranteed
  return this.findById(ctx.user!.id);
}

// Manual check (for more complex logic)
@api()
async updateProfile(ctx: Context, data: ProfileData) {
  if (!ctx.user) {
    throw new UnauthorizedException("Login required");
  }

  if (ctx.user.id !== data.userId) {
    throw new UnauthorizedException("You can only modify your own profile");
  }

  // Profile update logic
}